今最も熱いPHPのフレームワーク、Laravel
これから新たにLaravelを始める方も多いと思うので、Laravel6.0のディレクトリ構造について軽く解説したいと思います。
パートナーとして共に活動しているkahiro氏のLaravel5.3ディレクトリ構造の解説 を参考にしています。
プロジェクトルートディレクトリ一覧
プロジェクトのルートディレクトリで ls -al を実行したと時に表示されるディレクトリ及びファイルについて、Readouble Laravel 6.0 ディレクトリ構造の参考記事を引用しつつ解説します。
ディレクトリ一覧
app
Broadcasting *
Console
Events *
Exceptions
Http
Controllers
Middleware
Requests
Jobs *
Listeners *
Mail *
Notifications *
Policies *
Providers
Rules *
bootstrap
cache
config
database
migrations
seeds
factories
public
resources
js
lang
sass
views
routes
storage
app
framework
logs
tests
vendor
-
*はデフォルトでは存在しないディレクトリ
ファイル一覧
artisan
readme.md
server.php
composer.json
composer.lock
phpunit.xml
package.json
.editorconfig
.env
.env.example
.gitattributes
.gitignore
.styleci.yml
webpack.mix.js
イントロダクション
Laravelのデフォルトアプリケーション構造はアプリケーションの大小にかかわらず、素晴らしいスタートを切ってもらえることを意図しています。アプリケーションは皆さんのお好みに応じ、自由に体系立ててください。クラスがComposerによりオートローディングできるならば、Laravelはクラスをどこに配置するか強制することはまずありません。
modelsディレクトリはどこにある？
Laravelを学習し始めるとき、多くの開発者は
modelsディレクトリが存在しないことに戸惑います。しかし、意図的にこのディレクトリを用意していません。多くの別々の人達にとって、その意味合いは様々なため、"models"という言葉の定義は曖昧であることに私達は気づきました。ある開発者たちはすべてのビジネスロジックを総称してアプリケーションの「モデル」と呼び、一方で別の人達はリレーショナルデータベースに関連するクラスを「モデル」として参照しています。このため、私達はEloquentモデルをデフォルトではappディレクトリ下へ設置することを選択し、開発者自分が選んだどこか別の場所へ設置してもらうことにしました。
デフォルトでは app/User.php とモデルクラスを配置します。
小規模開発であればこの配置でも良さそうです。
システムが大きくなると app ディレクトリ直下にモデルクラスがたくさんできることになるので、無難に app/Models ディレクトリを区切っても良さそうです。
モデルの置き場は設計によるので、自由に配置できるLaravelはとても便利ですね！
appディレクトリ
appディレクトリは、アプリケーションのコアコードを配置します。このフォルダの詳細は、このあとに説明します。しかし、アプリケーションのほとんど全部のクラスは、このディレクトリの中に設定されることを覚えておいてください。
appディレクトリ内に業務で扱うクラスを配置します。
このディレクトリは重要なので、app配下のディレクトリについても説明します。
app/Broadcastingディレクトリ
このディレクトリはデフォルトで存在していません。
Broadcastingディレクトリは、アプリケーションの全ブロードキャストチャンネルクラスで構成します。これらのクラスは、make:channelコマンドで生成されます。最初にチャンネルを生成したときにこのディレクトリは作成されます。チャンネルについての詳細は、イベントブロードキャストのドキュメントで確認してください。
app/Consoleディレクトリ
Consoleディレクトリは、アプリケーションの全カスタムArtisanコマンドで構成します。これらのコマンドクラスはmake:commandコマンドにより生成されます。コンソールカーネルもこのディレクトリ内にあり、カスタムArtisanコマンドや、タスクのスケジュールを登録します。
app/Eventsディレクトリ
このディレクトリはデフォルトで存在していません。event:generateかmake:event Artisanコマンド実行時に作成されます。Eventsディレクトリは、イベントクラスを設置する場所です。イベントは特定のアクションが起きたことをアプリケーションの別の部分に知らせるために使われ、柔軟性と分離性を提供しています。
app/Exceptionsディレクトリ
Exceptionsディレクトリはアプリケーションの例外ハンドラで構成します。また、アプリケーションから投げる例外を用意するにも適した場所でしょう。例外のログやレンダー方法をカスタマイズしたい場合は、このディレクトリのHandlerクラスを修正してください。
app/Httpディレクトリ
Httpディレクトリはコントローラ、ミドルウェア、フォームリクエストを設置します。アプリケーションへのリクエストを処理するロジックは、ほぼ全てこのディレクトリ内に設置します。
app/Http/Controllersディレクトリ
全リクエストの処理をルートファイルのクロージャで定義するよりも、コントローラクラスにより組織立てたいと、皆さんも考えるでしょう。関連のあるHTTPリクエストの処理ロジックを一つのクラスへまとめ、グループ分けができます。コントローラはapp/Http/Controllersディレクトリ下に設置します。
app/Http/Middlewareディレクトリ
ミドルウェアはアプリケーションへ送信されたHTTPリクエストをフィルタリングする、便利なメカニズムを提供します。たとえば、アプリケーションのユーザーが認証されているかを確認するミドルウェアがLaravelに用意されています。ユーザーが認証されていなければ、このミドルウェアはユーザーをログインページへリダイレクトします。反対にそのユーザーが認証済みであれば、そのリクエストがアプリケーションのその先へ進むことを許可します。
認証の他にも多彩なタスクを実行するミドルウェアを書くことができます。たとえばCORSミドルウェアは、アプリケーションから返されるレスポンス全部に正しいヘッダを追加することに責任を持つでしょう。ログミドルウェアはアプリケーションにやってきたリクエスト全部をログすることに責任を負うでしょう。
認証やCSRF保護などLaravelには多くのミドルウェアが用意されています。これらのミドルウェアは全部、
app/Http/Middlewareディレクトリに設置されています。
app/Http/Requestsディレクトリ
より複雑なバリデーションのシナリオでは、「フォームリクエスト」を生成したほうが良いでしょう。フォームリクエストは、バリデーションロジックを含んだカスタムリクエストクラスです。フォームリクエストクラスを作成するには、
make:requestArtisan CLIコマンドを使用します。
app/Jobsディレクトリ
このディレクトリはデフォルトで存在していません。
make:jobArtisanコマンドを実行すると作成されます。Jobsディレクトリはアプリケーションのキュー投入可能なジョブを置いておく場所です。Jobsはアプリケーションによりキューに投入されるか、もしくは現在のリクエストサイクル中に同期的に実行されます。現在のリクエストサイクル中に同期的に実行するジョブは、コマンドパターンを実装しているため、時に「コマンド」と呼ばれることがあります。
app/Listenersディレクトリ
このディレクトリはデフォルトで存在していません。
event:generateかmake:listenerArtisanコマンドを実行すると、作成されます。Listenersディレクトリには、イベントを処理するクラスを設置します。イベントリスナはイベントインスタンスを受け取り、発行されたイベントへ対応するロジックを実行します。たとえば、UserRegistered（ユーザー登録）イベントは、SendWelcomeEmail（ウェルカムメール送信）リスナにより処理されることになるでしょう。
app/Mailディレクトリ
このディレクトリはデフォルトでは存在していません。
make:mailArtisanコマンドを実行すると、作成されます。Mail::sendメソッドを使用して送られるメールを組み立てるロジックをすべて、１つのシンプルなクラスへカプセル化できます。
app/Notificationsディレクトリ
このディレクトリはデフォルトでは存在していません。
make:notificationArtisanコマンドを実行すると作成されます。Notificationsディレクトリは、アプリケーションから送られる全「業務上」の通知、たとえばアプリケーションの中でイベントが発生したことを知らせるシンプルな通知などで構成します。Laravelの通知機能は、メール、Slack、SMS、データベースへの保存などのように、様々なドライバに対する通知の送信を抽象化しています。
app/Policiesディレクトリ
このディレクトリはデフォルトでは存在していません。
make:policyArtisanコマンドを実行すると、作成されます。Policiesディレクトリにはアプリケーションの認可ポリシークラスを設置します。ポリシーは、リソースに対し指定したアクションをユーザーが実行できるかを決定します。詳細は、認可のドキュメントをご覧ください。
app/Providersディレクトリ
Providersディレクトリは、アプリケーションの全サービスプロバイダにより構成します。サービスプロバイダは、サービスをコンテナと結合、イベントの登録、もしくはアプリケーションへやってくるリクエストを処理するために必要な用意をするタスクを実行するなど、アプリケーションの事前準備を行います。インストール直後のアプリケーションでも、このディレクトリは多くのプロパイダーを含んでいます。必要に応じて、自分のプロバイダを自由に追加してください。
app/Rulesディレクトリ
このディレクトリは、デフォルトでは存在していません。
make:ruleArtisanコマンドを実行すると、作成されます。Rulesディレクトリは、アプリケーションで使用するバリデーションルールオブジェクトで構成します。ルールは複雑なバリデーションロジックをシンプルなオブジェクトへカプセル化するために使用します。詳細は、バリデーションのドキュメントで確認してください。
bootstrapディレクトリ
bootstrapフォルダは、フレームワークの初期処理を行うapp.phpファイルを含んでいます。その中のbootstrap/cacheディレクトリは、初期処理のパフォーマンスを最適化するため、フレームワークが生成するルートやサービスのキャッシュファイルが保存されるフォルダです。
このbootstrapディレクトリに自分でコードを追加したり、編集したりといったことはまずないです。
configディレクトリ
configディレクトリは名前が示す通り、アプリケーションの全設定ファイルが設置されています。全ファイルに目を通し、設定可能なオプションに慣れ親しんでおくのは良い考えでしょう。
config で設定している値は .env ファイルで上書きできる項目もあります。
ここで設定している値は、config('ファイル名.キー値')とアクセスできます。
また、config/*.php と配置されている設定ファイル群は配列を返すだけなので。
新たに自身で新しくファイルを作れば、同様にconfig関数でアクセスできます。
databaseディレクトリ
databaseフォルダはデータベースのマイグレーションとモデルファクトリ、初期値設定（シーディング）を配置します。ご希望であれば、このファイルをSQLiteデータベースの設置場所としても利用できます。
database/migrationsディレクトリ
マイグレーションとはデータベースのバージョンコントロールのような機能です。アプリケーションデータベースのスキーマの更新をチームで簡単に共有できるようにしてくれます。マイグレーションは基本的にLaravelのスキーマビルダとペアで使い、アプリケーションのデータベーススキーマの作成を楽にしてくれます。もしあなたが今まで、チームメイトに彼らのローカルデータベーススキーマに手作業でカラムを追加するよう依頼したことがあるなら、データベースマイグレーションは、そうした問題を解決してくれます。
- データベースのテーブル構成のバージョン管理ツール
- マイグレーションクラスを配置する
- up, down は整合性に注意して書く
- Laravel 6.0 データベース：マイグレーション
database/seedsディレクトリ
シーダ（初期値設定）クラスを使用し、テストデーターをデーターベースに設定するシンプルな方法もLaravelには備わっています。全シーダクラスは
database/seedsに保存します。シーダクラスには好きな名前を付けられます。しかしUsersTableSeederなどのような分かりやすい規則に従ったほうが良いでしょう。デフォルトとしてDatabaseSeederクラスが定義されています。このクラスからcallメソッドを使い他の初期値設定クラスを呼び出すことで、シーディングの順番をコントロールできます。
database/factoriesディレクトリ
テスト実行前に、何件かのレコードをデータベースに挿入する必要があります。こうしたテストデータを作る時に、手動でそれぞれのカラムへ値を指定する代わりに、Laravelではモデルファクトリを使用し、Eloquentモデルの各属性にデフォルト値を設定できます。
publicディレクトリ
publicディレクトリには、アプリケーションへの全リクエストの入り口となり、オートローディングを設定するindex.phpファイルがあります。また、このディレクトリにはアセット（画像、JavaScript、CSSなど）を配置します。
resourcesディレクトリ
resourcesディレクトリはビューやアセットの元ファイル（LESS、SASS、JavaScript）で構成されています。また、すべての言語ファイルも配置します。
routesディレクトリ
ディレクトリはアプリケーションの全ルート定義により構成されています。デフォルトでは、
web.php、api.php、console.php、channels.phpファイルが含まれています。
web.phpファイルは、RouteServiceProviderのwebミドルウェアグループに属するルートで構成します。このミドルウェアは、セッションステート、CSRF保護、クッキーの暗号化機能を提供しています。もしアプリケーションがステートレスではなく、RESTフルなAPIを提供しないのであれば、すべてのルートはweb.phpファイルの中で定義されることになるでしょう。
api.phpファイルは、RouteServiceProviderのapiミドルウェアグループに属するルートで構成します。このミドルウェアはアクセス回数制限を提供しています。このファイル中で定義されるルートは、ステートレスであることを意図しています。つまり、これらのルートを通るアプリケーションに対するリクエストは、セッションステートにアクセスする必要がないように、トークンを使って認証されることを意図しています。
console.phpファイルは、クロージャベースの全コンソールコマンドを定義する場所です。それぞれのコマンドのIOメソッドと連携するシンプルなアプローチを提供するコマンドインスタンスと、各クロージャは結合します。厳密に言えば、このファイルはHTTPルートは定義していないのですが、コンソールベースのエントリポイントを定義しているという点で、ルート定義なのです。
channels.phpファイルはアプリケーションでサポートする、全ブロードキャストチャンネルを登録する場所です。
storageディレクトリ
storageディレクトリにはコンパイルされたBladeテンプレート、ファイルベースのセッション、ファイルキャッシュなど、フレームワークにより生成されるファイルが保存されます。このフォルダはapp、framework、logsディレクトリに分かれています。appディレクトリはアプリケーションにより生成されるファイルを保存するために利用します。frameworkディレクトリはフレームワークが生成するファイルやキャッシュに利用されます。最後のlogsディレクトリはアプリケーションのログファイルが保存されます。
storage/app/publicディレクトリにはプロファイルのアバターなどのようなユーザーにより生成され、外部からアクセスされるファイルが保存されます。public/storageがこのディレクトリを指すように、シンボリックリンクを張る必要があります。リンクは、php artisan storage:linkコマンドを使い生成できます。
testsディレクトリ
testsディレクトリには皆さんの自動テストを配置します。サンプルのPHPUnitテストが最初に含まれています。各テストクラスはサフィックスとしてTestを付ける必要があります。テストはphpunitか、php vendor/bin/phpunitコマンドにより実行できます。
vendorディレクトリ
vendorディレクトリには、Composerによる依存パッケージが配置されます。
artisanファイル
$ php artisan xxx
Laravelのartisanコマンドを叩く時に実行されているファイルです。
readme.mdファイル
READMEというのは、GitHub/Bitbucket等で公開されるソフトウェア（リポジトリ）の説明書きのことになります。
プロジェクトの概要説明から開発環境の立ち上げ、貢献方法への案内などを簡潔にまとめます。
.md 拡張子は文章を記述するための記法（マークアップ言語）です。
readme.md, README.md ファイル名は大文字でも小文字でもどちらでも構いません。
お好みです。
server.phpファイル
$ php artisan serve
ビルトインサーバー起動時に使用されます。
composer.jsonファイル
composer.jsonはPHPのパッケージ管理ツール「Composer」の設定ファイルで、インストールしたいパッケージをJSON形式で管理します。
また、オートローディングやスクリプトなどの設定もできます。
-
composer install-
composer.lockを参照します。 -
composer.lockがない場合、composer.jsonを参照します。
-
-
composer update-
composer.jsonを参照します。
-
composer.lockファイル(ロックファイル)
composer.lockはcomposer.jsonに記述したパッケージをインストールしたあとに、実際にインストールしたパッケージのバージョンのリストをcomposer.lockに書き込みます。
ロックファイルにより、プロジェクトメンバーは同一のバージョンで開発が行えます。
phpunit.xmlファイル
phpunit.xmlはPHP用のテスティングフレームワーク「PHPUnit」の設定ファイルです。
package.jsonファイル
Node.jsのパッケージ管理設定ファイルです。
パッケージ管理ツールとしてはnpmかyarnが使用されます。
npm installをするとnode_modulesというディレクトリが作成され、package.jsonに定義されたパッケージがインストールされます。
実際にインストールしたバージョンのリストをpackage-lock.jsonというロックファイルに作成します。
yarn installをするとnode_modulesというディレクトリが作成され、package.jsonに定義されたパッケージがインストールされます。
実際にインストールしたバージョンのリストをyarn.lockというロックファイルに作成します。
npm, yarnどちらも人気なパッケージ管理ツールだと思いますが、使用する場合はどちらか一方に統一して使用しましょう。
.editorconfigファイル
EditorConfigは、さまざまなエディターやIDEで一貫したコーディングスタイルを定義します。
文字コードや改行コード、インデントの数をファイル形式に毎に設定できます。
.envファイル
.env は環境設定ファイルです。
開発環境や本番環境で異なる設定を管理するファイルです。
基本的にGit管理対象外にするファイルです。
データベースの接続情報など機密性の高い情報を扱うため注意が必要です。
補足ですが、
.envファイルにあるすべての変数は、サーバレベルやシステムレベルで定義されている、外部の環境変数によってオーバーライドできます。
.env.exampleファイル
環境設定ファイルのサンプルファイルです。
プレースホルダーとして開発環境用の値を設定しておけば、チームメンバーはスムーズに開発環境の構築が行えます。
さらに.env.testingファイルを作成できます。このファイルはPHPUnitテスト実行時やArtisanコマンドへ--env=testingオプションを指定した場合に、.envファイルをオーバーライドします。
.gitattributesファイル
.gitattributesファイルはGitの属性設定ファイルです。
あまり意識しなくていいファイルだと思います。
.gitignoreファイル
.gitignoreファイルはGitの管理対象外設定ファイルです。
.env や vendor 等Gitで管理しないファイルやディレクトリを設定します。
.styleci.ymlファイル
.styleci.ymlファイルはコードチェックサービス「StyleCI」の設定ファイルです。
StyleCIはLaravel公式が利用しているサービスで、PHPやcss、jsのフォーマットをチェックし、自動で整形してくれるサービスです。
GitHub、GitLab、Bitbacketと連携ができ、各種ホスティングサービスにpushすると、自動的にチェックが行われます。プルリク単位やコード全体に対してチェックできます。
webpack.mix.jsファイル
webpack.mix.jsファイルはLaravel Mixの設定ファイルです。
webpackの設定をシンプルなメソッドチェーンで定義できるwebpackのラッパーライブラリです。