PHPCS-CakePHP2 ドキュメント

pieceofcake2/phpcs-cakephp2 は、pieceofcake2/cakephp で動作する CakePHP 2 のアプリケーションとプラグインのための PHP_CodeSniffer のコーディング規約 CakePHP2 です。現在の CakePHP のコーディング規約である cakephp/cakephp-codesniffer 5.x の CakePHP 規約をベースにしており、CakePHP 2 のコードに必要な例外だけを追加しています。

このパッケージは cakephp/cakephp-codesniffer をフォークしていません。cakephp/cakephp-codesniffer に依存し、その CakePHP 規約を参照しているので、新しい sniff や修正された sniff は通常の composer update で取り込まれます。

インストール
設定
ルール
例外の追加
CakePHP ベースの phpcs.xml からの移行
開発

インストール

Composer で、開発用の依存パッケージとして規約をインストールします。

bash

composer require --dev pieceofcake2/phpcs-cakephp2

これにより、PHP_CodeSniffer、cakephp/cakephp-codesniffer と dealerdirect/phpcodesniffer-composer-installer プラグインがインストールされます。このプラグインは CakePHP2 規約と CakePHP 規約を PHP_CodeSniffer に登録します。 Composer はプラグインを許可するか尋ねます。許可するか、自分で composer.json に追加してください。

json

{
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

規約が登録されていることを確認します。

bash

vendor/bin/phpcs -i
# The installed coding standards are ..., CakePHP2, CakePHP and SlevomatCodingStandard

PHP_CodeSniffer は PHP 8.1 以降で実行してください。プロジェクトの PHP 8.0 のテストジョブで composer install が動作するように、このパッケージは PHP 8.0 にもインストールできます。ただしその場合、Composer は cakephp/cakephp-codesniffer 5.1.0 にフォールバックし、その CakePHP 規約は現在の slevomat/coding-standard では読み込めません。phpcs.xml の php_version には、コードがサポートする最も古い PHP のバージョンを設定してください (後述)。

pieceofcake2/app スケルトンには、この規約がすでに設定されています。

設定

プロジェクトのルートに phpcs.xml ファイルを追加します。PHP_CodeSniffer はこのファイルを自動的に読み込むので、 vendor/bin/phpcs と vendor/bin/phpcbf に引数は必要ありません。

pieceofcake2/app のディレクトリ構成 (config/、src/、tests/) のアプリケーションでは、次のようにします。

xml

<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">
    <config name="php_version" value="80000"/>

    <arg value="ps"/>
    <arg name="colors"/>
    <arg name="parallel" value="16"/>
    <arg name="extensions" value="php,php.default"/>

    <file>./config</file>
    <file>./src</file>
    <file>./tests</file>

    <rule ref="CakePHP2"/>
</ruleset>

元の構成のアプリケーションでは、代わりに app/ 以下のディレクトリを列挙します。たとえば ./app/Config、 ./app/Controller、./app/Model、./app/View と ./app/Test です。プラグインでは、プラグイン自身のディレクトリ (Controller、Model、Lib、tests、...) を列挙します。

規約のパターンは、これらのディレクトリがどこにあってもマッチします。そのため Controller/ は、src/Controller/、 app/Controller/、プラグインの Controller/ のいずれも指します。

ルール

CakePHP2 は、CakePHP 規約に次の変更を加えたものです。インデント、短い配列構文、ドキュメントコメント、use 文など、それ以外はすべて CakePHP 規約のままです。

すべての場所で除外

Sniff	理由
`PSR1.Classes.ClassDeclaration.MissingNamespace`	CakePHP 2 のクラスはグローバル名前空間にあります。
`PSR1.Files.SideEffects.FoundWithSymbols`	クラスファイルの先頭にある `App::uses()` が副作用とみなされます。
`Squiz.Classes.ClassFileName.NoMatch`	CakePHP 2 には、クラス名と異なる名前のファイルがあります (例: `Config/Schema/schema.php`)。
`SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedNameWithoutNamespace`	名前空間がなければ、`\Exception` などのグローバルな名前をそのまま使ってかまいません。
`SlevomatCodingStandard.Namespaces.FullyQualifiedClassNameInAnnotation.NonFullyQualifiedClassName`	アノテーション内のクラス名はグローバルな名前です。
`SlevomatCodingStandard.TypeHints.PropertyTypeHint`	ネイティブの型は、CakePHP 2 のクラスとそのサブクラスが共有するシグネチャを変えてしまいます。型は docblock に記述します。
`SlevomatCodingStandard.TypeHints.ParameterTypeHint`	上と同じです。
`SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint`	上と同じです。テストは例外です。下の `CakePHP2.TypeHints.TestReturnTypeHint` をご覧ください。
`SlevomatCodingStandard.TypeHints.DeclareStrictTypes.DeclareStrictTypesMissing`	CakePHP 2 のコードは strict types を前提に書かれていません。
`Zend.NamingConventions.ValidVariableName.StringVarNotCamelCaps`	変数はモデルの名前で命名されます: `"{$Model->alias}"`。
`Zend.NamingConventions.ValidVariableName.PublicHasUnderscore`	CakePHP 2 にはアンダースコア付きの public プロパティがあります。
`Zend.NamingConventions.ValidVariableName.PublicVarHasUnderscore`	上と同じです。
`SlevomatCodingStandard.ControlStructures.AssignmentInCondition.AssignmentInCondition`	CakePHP 2 ではよく使われます: `while ($row = $result->fetch())`。
`CakePHP.Commenting.FunctionComment.SpacingAfter`	ドキュメントコメントの後の空行を許可します。
`Generic.Files.LineLength`	CakePHP 2 のコードベースの多くに長い行があります。

一部の場所で除外

Sniff	チェックしない場所	理由
`PSR1.Methods.CamelCapsMethodName.NotCamelCaps`	`/Controller/`、`/Console/Command/`、`/Model/Behavior/`	コントローラーのアクション (`admin_index`)、シェルのコマンド、ビヘイビアのメソッドはアンダースコアを使います。
`CakePHP.Commenting.FunctionComment.Missing`	`/tests/TestCase/`、`/Test/Case/`	テストメソッドにはドキュメントコメントは必要ありません。
`PSR1.Classes.ClassDeclaration.MultipleClasses`	`/tests/TestCase/`、`/Test/Case/`	テストファイルでは、テストケースの隣にテストダブルを宣言してもかまいません。
`Squiz.Classes.ValidClassName.NotPascalCase`	`/database.php`、`/database.php.default`	データソースの設定クラスは `DATABASE_CONFIG` です。
`Squiz.PHP.NonExecutableCode.Unreachable`	`*/acl.ini.php`	INI のデータが決して配信されないように、このファイルは `exit;` で始まります。

追加

Sniff 設定

Generic.Formatting.MultipleStatementAlignment maxPadding 1: 揃えた代入に追加できる空白は最大 1 つです。

CakePHP2.TypeHints.TestReturnTypeHint */tests/TestCase/* と */Test/Case/* では、すべてのメソッドと関数にネイティブの戻り値の型が必要です: setUp(): void、testFoo(): void、fooProvider(): array。PHPUnit はテンプレートメソッドをネイティブの型で宣言しており、テストメソッドを呼ぶのは PHPUnit だけなので、CakePHP 2 のほかのコードと違ってテストでは使えます。何も返さないメソッドには phpcbf が : void を追加します。コンストラクターはチェックしません (CakePHP 規約は tests/ では戻り値の型をまったくチェックしません)。

Sniff	設定
`Generic.Formatting.MultipleStatementAlignment`	`maxPadding` 1: 揃えた代入に追加できる空白は最大 1 つです。
`CakePHP2.TypeHints.TestReturnTypeHint`	`/tests/TestCase/` と `/Test/Case/` では、すべてのメソッドと関数にネイティブの戻り値の型が必要です: `setUp(): void`、`testFoo(): void`、`fooProvider(): array`。PHPUnit はテンプレートメソッドをネイティブの型で宣言しており、テストメソッドを呼ぶのは PHPUnit だけなので、CakePHP 2 のほかのコードと違ってテストでは使えます。何も返さないメソッドには `phpcbf` が `: void` を追加します。コンストラクターはチェックしません (`CakePHP` 規約は `tests/` では戻り値の型をまったくチェックしません)。

例外の追加

プロジェクト固有の例外は、規約の後に追加します。一部のファイルで sniff を無効にするには、次のようにします。

xml

<rule ref="CakePHP2"/>

<!-- PHP calls the methods of stream wrappers by fixed names (stream_open, url_stat, ...) -->
<rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
    <exclude-pattern>Lib/S3StreamWrapper.php</exclude-pattern>
</rule>

すべての場所で sniff を無効にするには、参照の中で除外します。

xml

<rule ref="CakePHP2">
    <exclude name="SlevomatCodingStandard.TypeHints"/>
</rule>

各メッセージの元になっている sniff の名前は、vendor/bin/phpcs -s を実行すると確認できます。

CakePHP ベースの phpcs.xml からの移行

このパッケージができるまで、pieceofcake2 のリポジトリと pieceofcake2/app スケルトンでは、上記の例外をすべての phpcs.xml の <rule ref="CakePHP"> の後に書き出していました。切り替えるには次のようにします。

依存パッケージを置き換えます。

bash

composer remove --dev cakephp/cakephp-codesniffer
composer require --dev pieceofcake2/phpcs-cakephp2

phpcs.xml で、<rule ref="CakePHP"> のブロックと、この規約が対応するようになったルール (MultipleStatementAlignment、FunctionComment.Missing、MultipleClasses、コントローラー、シェル、ビヘイビアに対する NotCamelCaps、ReturnTypeHint.MissingNativeTypeHint、database.php に対する NotPascalCase と acl.ini.php に対する Unreachable) を <rule ref="CakePHP2"/> に置き換えます。 <config>、<arg>、<file> の項目と、自分のファイルに対する例外はそのまま残してください。
vendor/bin/phpcs を実行します。1.1.0 からは、ネイティブの戻り値の型がないテストメソッドが報告されます (CakePHP2.TypeHints.TestReturnTypeHint)。vendor/bin/phpcbf で : void を追加し、ほかの戻り値の型は手で追加してください。

以前の設定には、tests/TestCase/ でネイティブの戻り値の型を必須にするためのルール (include pattern 付きの ReturnTypeHint.MissingNativeTypeHint) がありました。しかし CakePHP 規約は tests/ では戻り値の型をチェックしないので、このルールは一度も効果がありませんでした。その役割は CakePHP2.TypeHints.TestReturnTypeHint が担います。

開発

bash

composer install

# Run the tests: phpcs with the standard on the files in fixtures/
vendor/bin/phpunit

# Check the coding standard of the tests
vendor/bin/phpcs

composer test は両方を実行します。fixtures/valid/ には合格しなければならない CakePHP 2 のコードが、 fixtures/invalid/ には既知の違反を含むコードがあります。tests/RulesetTest.php には、ファイルごとに期待される sniff が列挙されています。CakePHP 規約は tests/ では一部の sniff をスキップするので、フィクスチャは tests/ の外に置いています。

PHPCS-CakePHP2 ドキュメント ​

インストール ​

設定 ​

ルール ​

すべての場所で除外 ​

一部の場所で除外 ​

追加 ​

例外の追加 ​

CakePHP ベースの phpcs.xml からの移行 ​

開発 ​

PHPCS-CakePHP2 ドキュメント

インストール

設定

ルール

すべての場所で除外

一部の場所で除外

追加

例外の追加

CakePHP ベースの phpcs.xml からの移行

開発