PHPCS設定ドキュメント

概要

このドキュメントでは、Slot Kouryakuプロジェクトで使用しているPHPCS（PHP Code Sniffer）の設定について説明します。

設定ファイル

• メイン設定ファイル: config/phpcs.xml
• WordPress Coding Standards: WordPress公式のコーディング規約に準拠

主要な設定内容

1. コメント句読点ルールの無効化

設定理由

日本語コメントではピリオドが不自然な場合が多く、英語圏向けのWordPress Coding Standardsの厳格な句読点ルールが日本語開発環境に適していないため、以下のルールを無効化しています。

無効化されているルール

<!-- コメント句読点ルールの無効化（ピリオド要求のみ） -->
<!-- 個別ルール除外 -->
<exclude name="Squiz.Commenting.InlineComment.InvalidEndChar" />
<exclude name="Squiz.Commenting.FunctionComment.ParamCommentMustEndWithFullStop" />
<exclude name="Squiz.Commenting.FunctionComment.ThrowsCommentMustEndWithFullStop" />
<exclude name="Squiz.Commenting.DocComment.ParamCommentMustEndWithFullStop" />
<exclude name="Squiz.Commenting.DocComment.ThrowsCommentMustEndWithFullStop" />
<exclude name="Generic.Commenting.DocComment.ParamCommentMustEndWithFullStop" />
<exclude name="Generic.Commenting.DocComment.ThrowsCommentMustEndWithFullStop" />
<exclude name="PEAR.Commenting.FunctionComment.ParamCommentMustEndWithFullStop" />
<exclude name="PEAR.Commenting.FunctionComment.ThrowsCommentMustEndWithFullStop" />

<!-- 包括的ルール除外（WordPress標準対応） -->
<exclude name="Squiz.Commenting.FunctionComment" />
<exclude name="Generic.Commenting.DocComment" />
<exclude name="PEAR.Commenting.FunctionComment" />

注意: WordPress標準が独自のルール定義を持っている可能性があるため、個別ルール除外と包括的除外を併用しています。

対象となるコメントタイプ

• インラインコメント: // コメント内容 のピリオド要求
• 関数パラメータコメント: @param タグのピリオド要求
• 例外コメント: @throws タグのピリオド要求
• ドキュメントコメント: 各種DocBlockコメントのピリオド要求

例

無効化前（エラーになる）:

/**
 * ユーザー情報を取得する
 * @param int $userId ユーザーID
 * @throws Exception データベースエラー
 */
public function getUser($userId) {
    // データベースから取得
}

無効化後（エラーにならない）:

/**
 * ユーザー情報を取得する
 * @param int $userId ユーザーID
 * @throws Exception データベースエラー
 */
public function getUser($userId) {
    // データベースから取得
}

2. その他の主要設定

ファイル名制約の緩和

<exclude name="WordPress.Files.FileName" />

• WordPressの厳格なファイル命名規則を緩和

ドキュメント要件の緩和

<exclude name="Squiz.Commenting.FileComment" />
<exclude name="Squiz.Commenting.ClassComment" />
<exclude name="Squiz.Commenting.FunctionComment.Missing" />
<exclude name="Squiz.Commenting.VariableComment.Missing" />

• 段階的な改善のため、必須ドキュメント要件を緩和

現代的なPHP構文の許可

<exclude name="WordPress.PHP.DisallowShortTernary.Found" />
<exclude name="Generic.Arrays.DisallowShortArraySyntax.Found" />
<exclude name="Universal.Arrays.DisallowShortArraySyntax.Found" />

• 短縮配列記法 [] の使用を許可
• 短縮三項演算子の使用を許可

変数名制約の緩和

<exclude name="WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase" />
<exclude name="WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase" />

• camelCase変数名の使用を許可

除外パターン

以下のディレクトリ・ファイルはPHPCSの対象外です：

• vendor/ - Composer依存関係
• node_modules/ - npm依存関係
• _build/ - ビルド成果物
• _old/ - 旧ファイル
• build/ - ビルド成果物
• reports/ - レポートファイル
• *.min.js, *.min.css - 圧縮ファイル
• *.css, *.js - フロントエンドファイル
• pastFunctions/ - 過去の関数
• tests/ - テストファイル

使用方法

基本的な使用方法

# 全ファイルのチェック
./vendor/bin/phpcs --standard=config/phpcs.xml

# 特定ファイルのチェック
./vendor/bin/phpcs --standard=config/phpcs.xml path/to/file.php

# 自動修正（可能な場合）
./vendor/bin/phpcbf --standard=config/phpcs.xml path/to/file.php

詳細レポート

# 詳細レポート
./vendor/bin/phpcs --standard=config/phpcs.xml --report=full

# 進捗表示
./vendor/bin/phpcs --standard=config/phpcs.xml --report=progress

設定の変更履歴

2025-01-13

• コメント句読点ルールの無効化を追加
• 日本語コメント環境に適した設定に調整
• 包括的なルール除外から個別ルール除外に変更

ルール名の確認方法

1. 利用可能なルール一覧の確認

# 利用可能なすべてのルールを表示
./vendor/bin/phpcs -i

# 特定の標準のルール一覧を表示
./vendor/bin/phpcs --standard=WordPress -i

# 特定のカテゴリのルールを表示
./vendor/bin/phpcs --standard=WordPress --sniffs=Squiz.Commenting -i

2. エラーからルール名を特定

# 詳細なエラー情報を表示（ルール名が含まれる）
./vendor/bin/phpcs --standard=config/phpcs.xml --report=full path/to/file.php

# 特定のファイルのエラーを確認
./vendor/bin/phpcs --standard=config/phpcs.xml core_src/Handler/ErrorHandler.php

3. ルールの詳細情報を確認

# 特定のルールの詳細を表示
./vendor/bin/phpcs --standard=WordPress --sniffs=Squiz.Commenting.FunctionComment.ParamCommentMustEndWithFullStop -i

4. 設定ファイルの検証

# 設定ファイルの構文チェック
./vendor/bin/phpcs --config-show

# 設定ファイルの詳細表示
./vendor/bin/phpcs --standard=config/phpcs.xml --config-show

5. 実際の使用例

# 利用可能な標準の確認
./vendor/bin/phpcs -i
# 出力例: The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, Modernize, NormalizedArrays, Universal, PHPCSUtils, WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra

# 設定ファイルの確認
./vendor/bin/phpcs --config-show
# 出力例: Using config file: /path/to/config/phpcs.xml

# エラーからルール名を特定（詳細レポート）
./vendor/bin/phpcs --standard=config/phpcs.xml --report=full path/to/file.php
# 出力例: FILE: path/to/file.php
#        FOUND 1 ERROR AFFECTING 1 LINE
#        1 | ERROR | [Squiz.Commenting.FunctionComment.ParamCommentMustEndWithFullStop] Parameter comment must end with a full stop

6. ルール名の命名規則

PHPCSのルール名は以下の形式で構成されています：

Standard.Category.Sniff.Rule

例:

• Squiz.Commenting.FunctionComment.ParamCommentMustEndWithFullStop
  • Squiz: 標準名
  • Commenting: カテゴリ名
  • FunctionComment: スニッフ名
  • ParamCommentMustEndWithFullStop: 具体的なルール名

主要な標準:

• Squiz: 一般的なコーディング規約
• Generic: 汎用的なルール
• PEAR: PEAR標準
• WordPress: WordPress専用ルール

参考資料

公式ドキュメント

• WordPress Coding Standards
• PHP_CodeSniffer Documentation
• Annotated Ruleset

ルール一覧・検索サイト

• WordPress Coding Standards Sniff List
• PHP_CodeSniffer Sniff List
• Squiz Standards
• Generic Standards
• PEAR Standards

設定例・ベストプラクティス

• WordPress Coding Standards Configuration Examples
• PHP_CodeSniffer Configuration Examples
• Custom Ruleset Examples

トラブルシューティング

• Common Issues and Solutions
• WordPress Standards Issues

注意事項

• この設定は日本語コメント環境に特化しています
• 英語圏のプロジェクトでは、ピリオド要求ルールを有効にすることを推奨します
• セキュリティ関連のルールは適切に設定されているため、変更時は注意が必要です