Laravelドキュメントの読み方
タグ： Laravel5.1LTS Laravel
Laravelリファレンス発売記念アドベントカレンダー、2015年12月4日です。
他のフレームワークに慣れているのであれ、PHPを学び始めたばかりであれ、Laravelを学び始めるには、何か手がかりが必要です。英語が達者でしたら有料チュートリアルのLaracastsをみっちりと一ヶ月くらいでやり切るのが、まとまった情報をしっかりと学習でき、しかもお得でよろしいでしょう。
しかし、情報の基本はやはり公式ドキュメントです。
Laravel公式ドキュメント
世界で唯一の公式ドキュメントです。Taylorさんが管理しており、英語です。随時、変更がかかっています。
右上でバージョンを選択します。数字はそのままバージョンを示します。Masterは次期リリースバージョンです。これをタイプしている時点では5.2がリリース前ですので、現状のMasterは5.2向けのドキュメントというわけです。5.2がリリースされたら、Masterは5.3リリース予定のドキュメントになります。
公式ドキュメントはそのページで扱う主題の基本を簡単に説明します。説明はコードベースです。サンプルコードを示しながら、大まかな使い方を示しています。
時々、「全部が書かれていない、全部を書くべきだ」という意見が見受けられます。それも一つの考え方ですが、管理する方にとってはメンテが面倒になり、読む方にとってはボリュームが大幅に増えます。それでは習得するための負担が大きくなります。
ですから、公式ドキュメントは基本的な部分の使い方を説明しているものであると理解しておきましょう。全てが書かれているわけでありません。
どこから読むか
順番的にはインストールやチュートリアルが良いのです。概念やソースコードばかりを眺めていても、大して身につきません。やはり、手を動かして見るのが習得には早いようです。環境を作成し、チュートリアルを実際に行ってみるのが、わかりやすいでしょう。
（ここで宣伝です。Laravelリファレンスではサンプルプロジェクトを用意します。最初はLaravelの認証機能を利用して、ユーザーの簡単なCRUDを紹介しています。コメントでLaravel初心者が理解しづらい箇所のヒントをたくさん入れています。）
しっかりと基礎から勉強したい場合、次に読むべきはナビに「基本」としてカテゴライズされているページです。Webアプリケーションの基本的なコンポーネントについて説明されています。
実際は、その前に全体を把握するため、「リクエストのライフサイクル」のページをおすすめしたいのですが、5.1になり内容が整理され簡素になりすぎました。しかも文字ばかりです。理想的にはSymfonyのようにリクエストとレスポンスを図も使用し、解説をするところから説明してもらいたいところですが、これは考え方の違いですので、致し方ありません。
Webアプリケーションの基本を学習したことがない方は、事前にWeb上の情報のやり取りの基本を簡単に学習しておくことをおすすめします。フレームワークを便利なメソッドの塊として捉えても、それぞれのコンポーネントの関連が理解しづらいと思います。やはり、Webアプリケーションのフレームワークを理解するには、ベースとしてリクエストとレスポンス、リダイレクト程度については最低限押さえておきましょう。
ドキュメント日本語訳
手前味噌ですが、私が日本語に訳しているLaravelのドキュメントです。
本家と異なり、以前のバージョンにはほとんど手を入れていません。実際は、本家も古くなったバージョンはほとんど更新されないのですが、更に輪をかけて手を入れていません。
本家の最新バージョンは頻繁に何かしらの変更が入ります。時には、行末の改行コードの変更だったりします。非常に煩雑なため日本語訳には、ある程度原文の変更がまとまってから反映します。原文の変更箇所が自動で改変されるようにローカルに環境を組んでいるのですが、100％完全自動ではありません。変更の適用抜けを確認するために全体をざっと毎回調べます。ドキュメントの量が多いため、丁寧に調べていると８時間ほどかかりますので、原文の変更のたびにおこなうわけには行きません。そのため、月に一度程度の改定になっています。
次期リリースバージョンは翻訳していません。次期リリースバージョンは不安定な部分や補足の情報が必要な部分があります。使用するのであれば、ドキュメント以外の情報を英語で集める必要があります。日本語訳を必要としている人は、英語が苦手な人でしょうから、情報を集めたり、トラブル時に自力で解決したりできないでしょう。そのため、訳出していません。
ちなみに、readouble.comへのアクセスの一割は海外からです。多分私と同じように、公式の色使いが目に染みる人が多いのではないかと思っています。
API
ソースより生成されたAPIです。DEVバージョンが開発中、つまり次期バージョン向けです。
正直、Laravelにある程度親しんでくると、APIをわざわざWebで調べるより、ソースコードを直接読むようになってくるかと思います。IDEをうまく使えば、必要な部分へ移動しながらコードがチェックできます。わざわざ、Webページの情報を調べる必要はありません。
しかし、APIはIDEではなくエディターでソース編集をしている人には便利でしょう。（エディターでもSearch Everythingタイプの検索をうまく使えば、移動はさほど面倒でありません。）
そして、ソースコード
Laravelではコメントもドキュメントの一部として考えられています。その割には、過去バージョンでコメントが違っていたり、最新状態に追いついていなかったりと問題もありましたが、最近はユーザーの貢献もあり、大分まともになっています。
中級者以上の人であれば、ソースを読んで利用法を理解したり、必要なメソッドを探したりするのは面倒ではありません。Laravelのコードは比較的きれいで、簡単に書かれています。コメントも入っています。究極のドキュメントです。
逆に言えば、Laravelのソースが追えるようになれば、もう中級者以上でしょう。
様々なWebの情報
最近は日本語の情報もたくさん出るようになりました。Q&Aサイトで質問しても、答えは得られます。
どこを参考にするにせよ、当サイトも含め、解説者の意見が多かれ少なかれ反映されている内容であることに、留意しておくべきです。時々、こうしたWeb上の意見を元にLaravel（に限りませんが）を判断している人が見受けられます。公式ドキュメントの意見と相反しているのにです。
基本は公式ドキュメントです。欲しい情報がズバリ書かれていなくても、考え方や傾向は読み取れるはずです。ぜひ、全体を一読してください。
Laravelリファレンス
今回、新しく出版される「Laravelリファレンス」はどのような位置づけでしょうか。
少々内輪話をばらすと、当初は値段的にも中級者向けに企画されました。次に、マーケティング的には多少Laravel初心者向けの内容を含めたほうが良いだろうとなりました。実際に書き終えると、予定ページ数の倍程度になりました。そこで、メイン部分は書籍へ、書籍としてはコアな部分とLaravelを補助する部分の説明は電子書籍へと分けることとなりました。分割作業に伴う作業量の増加で、出版は当初より大きく遅れました。
結果、紙媒体の「Laravelリファレンス」は、「やや初心者から中級」レベルの方向けの内容です。Laravel初心者よりに簡単に全容を説明している初めの部分と、Webアプリケーションの基本となるコンポーネントの解説部分やテストの解説、それに実戦向けの内容としてセキュリティーやAritsanコマンドラインにも触れています。最後のサンプルアプリケーションは、実際にどうやってアプリケーションを作るべきか悩んでいる方に参考になるでしょう。
前書の「養成読本」はムック本で各章が独立して書かれました。そのため、各章がバラバラであるという印象をお持ちの方も多かったと思います。
本書も担当を割り振り、独立して書いていますが、内容の精査や校正を出版一ヶ月を切った今でも続けています。印刷屋さんを待たせて（怒っているそうです）、ぎりぎりまで調整しています。ですから前書よりは、かなり内容がまとまった一冊になっています。（ただ、完全にやりきれていないところが残念です。）
リファレンスとしての特徴から、公式ドキュメントと内容がかぶる部分も多いのです。しかし、「紙で読みたいという要求がある」、「書籍として内部で完結する必要がある」ということです。私の素直な感想では、必要としている人と、しない人とがはっきりと別れる書籍であろうと感じています。そのため、書店に本書が並ぶ都会の方には、一度手に取り、内容が自分や会社にあっているかを確認してから購入していただくのがよいかと思います。
スピンオフとして出版される電子書籍の内容は、ComposerやGit（これから私が書いたら入るかもしれません。簡単な解説）などLaravelの周辺ツールの解説、コレクションやヘルパー、パッケージの作成やWebアプリの流れの解説などになります。初心者よりのツール解説と、中級から上級向けのコアな内容と分かれそうです。実際、内容の詳細はまだ未定ですが、電子書籍は出版までのサイクルが早いため、さほど遠からずリリースされるでしょう。