Laravel入門 コーディング規約PSR12への対応とphp_codesniffer(第19回)

2021-01-01
8 min read

コーディング規約とは、視認性、保守性を一定以上にするためプログラムの書き方を定めるものです。 チーム開発する上で必要不可欠なものであり、開発チームに参加するためには標準的なコーディング規約を知っておく必要があります。

PHPのコーディング規約

Laravel を用いての開発で、従うべきコーディング規約は、特に定められてはいません。各々のプロジェクトが個別に定めることになります。 しかし、個別にコーディング規約を作成できるプロジェクトは大規模なプロジェクトか、歴戦の Laravel 職人を有するプロジェクトでないと難しいでしょう。 そこで、Laravel 本体が採用しているコーディング規約を取り入れます。

「Laravel 本体は PSR-2 コーディング規約と PSR-4 オートローディング規約に準拠しています」と公式ドキュメントの翻訳に記載されています。

https://readouble.com/laravel/7.x/ja/contributions.html

PSR (PHP Standards Recommendations) とは、PHP-FIG (PHP Framework Interop Group) が策定している PHP コーディング規約です。 しかし、その PHP-FIG によれば、「Deprecated - As of 2019-08-10 PSR-2 has been marked as deprecated. PSR-12 is now recommended as an alternative.」となっています。PSR-2 は廃止され PSR-12 がその代わりとなっているようです。

よって、PSR-12 を使うことになります。

コーディング規約をチェックするのは人力ではたいへんですので、ツールを使用します。 PSR-12 に対応しているツールとして、php_codesniffer というものを導入します。

php_codesnifferのインストールと設定

php_codesniffer をコンポーザーでプロジェクトにインストールします。

$ composer require --dev squizlabs/php_codesniffer

設定ファイルphpcs.xmlをプロジェクトルートに配置します。

$ touch phpcs.xml
<?xml version="1.0"?>
<ruleset name="PSR12">
    <!-- 拡張子が php のものにだけ適用 -->
    <arg name="extensions" value="php" />
    <!-- rule に PSR12 を指定可能 -->
    <rule ref="PSR12" />

    <!-- 変数名をキャメルケースに(Laravel固有ルール) -->
    <rule ref="Squiz.NamingConventions.ValidVariableName.NotCamelCaps"/>


    <!-- オプション p:進捗表示  s:エラー表示時にルールを表示 -->
    <arg value="ps" />

    <!-- 対象のファイル、ディレクトリ -->
    <file>app</file>
    <!-- 対象外のファイル、ディレクトリ -->
    <exclude-pattern>app/Http/Controllers/Controller.php</exclude-pattern>
    <exclude-pattern>app/Http/Controllers/BasicController.php</exclude-pattern>
    <exclude-pattern>app/Console/Kernel.php</exclude-pattern>

    <!-- testsディレクトリ配下はメソッド名のキャメルケースチェックを除外する -->
    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
        <exclude-pattern>*/tests/*</exclude-pattern>
    </rule>
</ruleset>
補足 : VSCODEで自動フォーマット

VSCODE で、拡張機能として、PHP Sniffer & Beautifierをインストールします。 設定として、/var/www/html/.vscode/settings.jsonとファイルを作成して、下記を設定内容とします。

{
  "editor.formatOnSave": true,
  "phpsab.autoRulesetSearch": false,
  "phpsab.standard": "./todo/phpcs.xml",
  "phpsab.executablePathCS": "./todo/vendor/bin/phpcs",
  "phpsab.executablePathCBF": "./todo/vendor/bin/phpcbf",
  "phpsab.snifferMode": "onSave"
}

ファイル保存時に自動でフォーマットされます。

コーディングチェック

$./vendor/bin/phpcs --standard=phpcs.xml

コーディング規約違反があれば下記のようなものが表示されます。

E.......E......EEEEEEE. 23 / 23 (100%)



FILE: /var/www/html/todo/app/Task.php
---------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
---------------------------------------------------------------------------------------------------
 19 | ERROR | [x] Whitespace found at end of line
    |       |     (Squiz.WhiteSpace.SuperfluousWhitespace.EndLine)
---------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
---------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Middleware/TrimStrings.php
---------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
---------------------------------------------------------------------------------------------------
 44 | ERROR | [x] Whitespace found at end of line
    |       |     (Squiz.WhiteSpace.SuperfluousWhitespace.EndLine)
---------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
---------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/LoginController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 22 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/RegisterController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 25 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/VerificationController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 22 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/ForgotPasswordController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 21 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/ResetPasswordController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 22 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/Auth/ConfirmPasswordController.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 22 | ERROR | [x] The first trait import statement must be declared on the first non-comment line after the class opening brace
    |       |     (PSR12.Traits.UseDeclaration.UseAfterBrace)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: /var/www/html/todo/app/Http/Controllers/TaskController.php
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 6 ERRORS AFFECTING 6 LINES
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  17 | ERROR | [x] No space found after comma in argument list (Generic.Functions.FunctionCallArgumentSpacing.NoSpaceAfterComma)
  18 | ERROR | [x] No space found after comma in argument list (Generic.Functions.FunctionCallArgumentSpacing.NoSpaceAfterComma)
  19 | ERROR | [x] Whitespace found at end of line (Squiz.WhiteSpace.SuperfluousWhitespace.EndLine)
  20 | ERROR | [x] Function closing brace must go on the next line following the body; found 1 blank lines before brace
     |       |     (PSR2.Methods.FunctionClosingBrace.SpacingBeforeClose)
  95 | ERROR | [x] Whitespace found at end of line (Squiz.WhiteSpace.SuperfluousWhitespace.EndLine)
 111 | ERROR | [x] Expected 1 space between comma and argument "$afterStatus"; 0 found (Squiz.Functions.FunctionDeclarationArgumentSpacing.NoSpaceBeforeArg)
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 6 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Time: 108ms; Memory: 10MB

ソース自動修正

上記の出力結果で、[x]が付いているものは自動で修正することができます。 上記の場合は、全てのものに[x]が付いています。

以下のコマンドで修正を行います。

$./vendor/bin/phpcbf --standard=phpcs.xml

以下のように修正結果が表示されます。

F.......F......FFFFFFF. 23 / 23 (100%)



PHPCBF RESULT SUMMARY
-----------------------------------------------------------------------------------------------
FILE                                                                           FIXED  REMAINING
-----------------------------------------------------------------------------------------------
/var/www/html/todo/app/Task.php                                                1      0
/var/www/html/todo/app/Http/Middleware/TrimStrings.php                         1      0
/var/www/html/todo/app/Http/Controllers/Auth/LoginController.php               1      0
/var/www/html/todo/app/Http/Controllers/Auth/RegisterController.php            1      0
/var/www/html/todo/app/Http/Controllers/Auth/VerificationController.php        1      0
/var/www/html/todo/app/Http/Controllers/Auth/ForgotPasswordController.php      1      0
/var/www/html/todo/app/Http/Controllers/Auth/ResetPasswordController.php       1      0
/var/www/html/todo/app/Http/Controllers/Auth/ConfirmPasswordController.php     1      0
/var/www/html/todo/app/Http/Controllers/TaskController.php                     6      0
-----------------------------------------------------------------------------------------------
A TOTAL OF 14 ERRORS WERE FIXED IN 9 FILES
-----------------------------------------------------------------------------------------------

Time: 189ms; Memory: 10MB

Laravel 特有のコーディング規約

PSR-12 では定められていない Laravel 特有の規約や慣習というものをベストプラクティスとしてまとめられているものがあります。

https://github.com/alexeymezenin/laravel-best-practices/blob/master/japanese.md

これを土台としてプロジェクトに合わせて取捨選択してコーディング規約を作成していくのがベターです。

たとえば、「コミュニティに受け入れられた標準の Laravel ツールを使う」という章では、開発環境は Docker ではなく Homestead を使うべきとなってはいます。 しかし、少し古いです。Laravel 自身も Ver8 にてLaravel Sailという Docker ベースの開発環境を出してきました。

こういったものもあるので、取捨選択が必要となってきます。

ただ、コーディング規約の中に命名規則というものがあります。これについては、このベストプラクティスをそのまま導入した方がよいでしょう。

以下、命名規則をhttps://github.com/alexeymezenin/laravel-best-practices/blob/master/japanese.mdより抜粋

対象 規則 Good Bad
コントローラ 単数形 ArticleController ArticlesController
ルート 複数形 articles/1 article/1
名前付きルート スネークケースとドット表記 users.show_active users.show-active, show-active-users
モデル 単数形 User Users
hasOne または belongsTo 関係 単数形 articleComment articleComments, article_comment
その他すべての関係 複数形 articleComments articleComment, article_comments
テーブル 複数形 article_comments article_comment, articleComments
Pivotテーブル 単数形 モデル名のアルファベット順 article_user user_article, articles_users
テーブルカラム スネークケース モデル名は含めない meta_title MetaTitle; article_meta_title
モデルプロパティ スネークケース $model->created_at $model->createdAt
外部キー 単数形 モデル名の最後に_idをつける article_id ArticleId, id_article, articles_id
主キー - id custom_id
マイグレーション - 2017_01_01_000000_create_articles_table 2017_01_01_000000_articles
メソッド キャメルケース getAll get_all
リソースコントローラのメソッド 下記で説明 store saveArticle
テストクラスのメソッド キャメルケース testGuestCannotSeeArticle test_guest_cannot_see_article
変数 キャメルケース $articlesWithAuthor $articles_with_author
コレクション 説明的、 複数形 $activeUsers = User::active()->get() $active, $data
オブジェクト 説明的, 単数形 $activeUser = User::active()->first() $users, $obj
設定ファイルと言語ファイルのインデックス スネークケース articles_enabled ArticlesEnabled; articles-enabled
ビュー ケバブケース show-filtered.blade.php showFiltered.blade.php, show_filtered.blade.php
コンフィグ スネークケース google_calendar.php googleCalendar.php, google-calendar.php
契約 (インターフェイス) 形容詞または名詞 AuthenticationInterface Authenticatable, IAuthentication
Trait 形容詞 Notifiable NotificationTrait

しかし、これを絶対唯一の正解と考えない事です。プロジェクトによって多少異なってきます。 上記えは、ビューのファイル名の命名規則は、ケバブケースでshow-filtered.blade.phpとなっています。一方、別のベストプラクティス https://www.laravelbestpractices.com/ では、show_filtered.blade.php とかかれており、スネークケースです。

リソースコントローラのメソッド

現状のルートを表示するコマンドが下記になります。

$ php artisan route:list

tasksに関係するものに絞ると下記になります。

項目番号 Method URI Name Action Middleware
1 POST tasks task.submit App\Http\Controllers\TaskController@store web
2 GET tasks/create task.new App\Http\Controllers\TaskController@create web
3 GET tasks/{id} task.edit App\Http\Controllers\TaskController@edit web
4 PUT tasks/{id} task.update App\Http\Controllers\TaskController@update web
5 DELETE tasks/{id} task.delete App\Http\Controllers\TaskController@destroy web
6 GET tasks/{id}/status/{afterstatus} task.updateStatus App\Http\Controllers\TaskController@updateStatus web
7 GET tabindex/{tabindex} tasklist App\Http\Controllers\TaskController@index web
8 GET / home App\Http\Controllers\TaskController@index web

laravelの標準的なルートは下記になります。 https://laravel.com/docs/master/controllers#resource-controllers

項目番号 Verb URI Action Route Name
A GET /photos index photos.index
B GET /photos/create create photos.create
C POST /photos store photos.store
D GET /photos/{photo} show photos.show
E GET /photos/{photo}/edit edit photos.edit
F PUT/PATCH /photos/{photo} update photos.update
G DELETE /photos/{photo} destroy photos.destroy

現状のルートの命名とLaraveiの標準的なものとを比較します。

項番1 新規登録

1に該当するのがCになります。 name が task.submit としていますが、tasks.store の方が望ましいようです。 修正します。

項番2 新規登録表示

2に該当するのがBになります name が task.new としていますが、tasks.create の方が望ましいようです。 修正します。

項番3 編集表示

3に該当するのがEになります URIが、tasks/{id}としていますが、/tasks/{id}}/editの方が望ましいようです。 修正します。

項番4 更新

4に該当するのがFになります name が task.update としていますが、tasks.update の方が望ましいようです。 修正します。

項番5 削除

5に該当するのがGになります

name が task.delete としていますが、tasks.destroy の方が望ましいようです。 修正します。

項番6 ステータス更新

6に該当するのはありません。 しかし、name が task.updateStatus としていますが、tasks.updateStatus の方が望ましく思われます。 修正します。

項番7 タブ切り替え

リソースに対するものではないので、該当するものはありません。

項番8 index

8に該当するのがAになります。 しかし、ここではtasksというリソースを表示するというよりもホーム画面に戻るという意味が強いのでこのままにします。

修正後のテスト

フューチャーテストを一括で行います。

$ ./vendor/bin/phpunit tests/Feature/

エラーがある場合は、個別にテストを実行してエラー修正してください。

個別テストOK。しかし全体一括NGの場合

個別にテストを実行していくと、テストに合格するが、一括でテストをするとエラーとなる場合があります。 PHPUNITの設定を修正する必要があります。

プロジェクト直下のphpunit.xmlを修正します。 phpunit の項目に、processIsolation=“true” を追加してください。

<phpunit 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd" 
  processIsolation="true"
  bootstrap="vendor/autoload.php" 
  colors="true">

詳細なエラー表示

TaskTabChangeTestクラスのtestReadyListOnly()メソッドのエラーを詳細に知りたい場合は、下記のようにメソッドの頭に$this->withoutExceptionHandling();を追加してください。

class TaskTabChangeTest extends TestCase
{
    use RefreshDatabase;

    public function testReadyListOnly()
    {
        $this->withoutExceptionHandling();

メソッドを指定してテストを実行するには、--filterを使用します。

./vendor/bin/phpunit tests/Feature/TaskTabChangeTest.php --filter 'testReadyListOnly'

ブラウザテストを一括で行います。

$ php artisan dusk

Tests\Browser\TodoListsTest::testExample がエラーになると思います。 これは、役目が終わったテストコードですので削除してください。

まとめ

コーディング規約以外にも、静的解析ツール・PHPDocの規約・コード補完のためのツールなど取り入れるべきものがあります。 それについてはシーズン 2 で対応していきます。