最近のPHPDocでの型の書き方

最近のPHPDocでの型の書き方が覚えられないので、まとめておきます。

配列

キーと値の型

キーがTKey、値がTValue

/**
 * @param array<TKey, TValue> $array
 */

キーがint、値がstring

/**
 * @param array<int, string> $array
 */

キーがint、値がint

/**
 * @param array<int, int> $array
 */

[10 => 100, 20 => 200, 30 => 300] のような配列で要素数は不明。

オブジェクトっぽい配列

以下の配列の場合、

$array = ["hello", "world", "foo" => new stdClass, 28 => false];

以下のように書きます。

/**
 * @param array{0: string, 1: string, foo: stdClass, 28: false} $array
 */

オプションのキーには?を最後に付けます。

/**
 * @param array{optional?: string, bar: int} $array
 */

以下の配列は、どちらも同じで、int の要素が 2つの [10, 20] のような配列です。

/**
 * @param array{0: int, 1: int} $array1
 * @param array{int, int} $array2
 */

リスト

リストとはキーが 0 から始まる連番の配列です。array_is_list() で true となる配列です。

/**
 * @param list<string> $array
 */

スカラー

配列のキー

array-keyintstringのスーパータイプです。

/**
 * @param array-key $key
 */

正の整数

/**
 * @param positive-int $positiveInt
 */

クラス文字列

/**
 * @param class-string $classname
 */

型を指定することもできます。

/**
 * @param class-string<A> $classname
 */

callable文字列

/**
 * @param callable-string $callable
 */

ジェネリクス

/**
 * @template T
 * @param T $a
 * @return T
 */
function foo($a)
{
    return $a;
}

引数 $a の型は T(型変数)で、返り値の型は引数と同じになります。

参考

Tags: php, phpstan, psalm

PHP静的解析でのエラーの抑制

(最終更新:2022-12-05)

静的解析でのエラーの抑制方法をすぐに忘れてしまうので、まとめておきます。

PHP_CodeSniffer

複数行

// phpcs:disable Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed
...
...
// phpcs:enable

1行

// phpcs:ignore Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed
$foo = [1,2,3];
$foo = [1,2,3]; // phpcs:ignore Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed

PHPMD

/**
 * @SuppressWarnings(PHPMD.UnusedLocalVariable)
 */

PHPStan

1行

// @phpstan-ignore-next-line
echo $foo;
echo $foo; // @phpstan-ignore-line

Psalm

/**
 * @psalm-suppress InvalidReturnType
 */

PHPUnit

静的解析ではありませんが、カバレッジ対象から除外する場合。

ブロック

/**
 * @codeCoverageIgnore
 */

複数行

// @codeCoverageIgnoreStart
print '*';
// @codeCoverageIgnoreEnd

1行

exit; // @codeCoverageIgnore

Rector

@noRector廃止されました。

Tags: php, phpstan, psalm, rector

ci-phpunit-testの正式リリース(v1.0.0、v2.0.0、v3.0.0)

初の正式リリース

2021/03/03にCodeIgniter 3でPHPUnitでのテストを簡単に書くためのツール「ci-phpunit-test」のv1.0.0、v2.0.0、v3.0.0をリリースしました。

調べてみると、最初のリリースv0.1.0は2015/06/12でした。 ということで、「構想3か月、開発5年」みたいな長大なプロジェクトに結果的になりました。

ここまでで合計38回のリリース、18人のコントリビューター、Composerからの累計ダウンロード数37万回以上になりました。

ただし、GitHubスターがまだ536と少ないです。特に日本人は少ないので、ユーザーのかたは遠慮なくスターをガンガン押してください!

PHPUnitのバージョンとの対応

何故、3つもバージョンをリリースしたかというと、PHPUnit(とPHP)のバージョンアップに対応するためです。今のところそれ以外に機能的な差異はありません。

PHPUnitでテストを書いていますが、ブランチを分けないとテストが簡単に書けなくなりました。

ci-phpunit-test PHP PHPUnit
v3.0.0 PHP 7.3以降 PHPUnit 9.3以降
v2.0.0 PHP 7.2以降 PHPUnit 8.1から9.2
v1.0.0 PHP 5.4.0以降 (5.6以降を推奨) PHPUnit 4.3から7.5 (4.8以降を推奨)

今後

今後は、v3.xをメインのバージョンとして、必要があれば古いバージョンもメンテしていこうと思います。

CodeIgniter4への対応

なお、ci-phpunit-test for CodeIgniter4の作成予定はありません。これは、多くの機能がCodeIgniter4に含まれたため、必要性があまりないためです。

ただし、全ての機能がCodeIgniter4に含まれるわけではないので、以下のパッケージで不足する機能(モック作成のヘルパーメソッド、モンキーパッチ、$this->request)を提供していきます。

以下のテストコードのように既存のテストコードをあまり変更せずにCodeIgniter4でも使えるようになります。

モンキーパッチについて

最後に、今までモンキーパッチについて、きちんと説明を書いたことがないので、ここに記載しておきます。

モンキーパッチは自転車の補助輪のようなものです。プロダクトコードに問題がなければ、本来必要ありません。個人的にも私は自分が書いたコードでモンキーパッチを使ったことはありません。

モンキーパッチを使わないとテストが書けない場合は、設計に問題があると思ってほぼ間違いありません。設計を見直してください。

そうは言っても、サードパーティのツールがexit()していたり、過去のレガシーコードをまだ使わざるを得なくモックに差し替えられないというような場合のために、一応、機能を提供しています。

できるだけ早く、モンキーパッチを使わなくて済む環境を目指してください。

関連

Tags: codeigniter, phpunit, testing, release