PHPサンプルをGitHubで公開する｜分類・README・導入確認

2026年11月1日

Laravel
PHP

PHPサンプルの分類とREADMEの役割、GitHubから取得して導入・確認する流れ

PHPのサンプルコードは、Laravel以外のものも追加していく予定です。
そこで、サンプル集のphp-samplesを用意し、Laravelのアプリはlaravel/learning-app/へまとめる構成にしました。
今回は、コードを置くだけでなく、初めて取得した人が導入して動かせるようにREADMEと確認手順を整えます。

説明は2026年11月1日時点のものです。
この記事では、サンプル集の整理からGitHubへのPush、導入・動作確認までを扱います。
整理したコードとREADMEをGitHubで公開しました。
サンプルコードと導入手順は、GitHubのphp-samplesにまとめています。
公開したコードをGitHubから新しく取得し、READMEの手順で導入・動作確認も行いました。

目次 [ close ]

分類とアプリを分けて置く

リポジトリのルートには全体の案内を置き、実際のアプリは分類フォルダーの下に置きます。
Laravel以外のサンプルが増えたときも、アプリのファイルと混ざらないようにするためです。

php-samples/
├── README.md
├── LICENSE
└── laravel/
    └── learning-app/
        ├── README.md
        ├── .env.example
        ├── composer.json
        ├── composer.lock
        ├── package.json
        ├── package-lock.json
        ├── app/
        ├── resources/
        ├── routes/
        └── tests/

ルートのREADMEはサンプル一覧、アプリのREADMEは導入・起動・テストの説明を担当します。
新しい分類は、対応するサンプルを追加するときに作ります。

今回のLaravelアプリには、共通メニュー、パスワード生成、Hello World、名前を送る入力フォームを含めました。
一部の画面だけを抜き出すのではなく、ルート・コントローラー・Blade・サービスとテストをまとめて配置しています。

再現に使うファイルと、動かした後のファイルを分ける

同じコードを動かすためのソースと、実行中に作られるデータは分けて扱います。

公開用に含めるもの	目的
ソースコード・テスト	実装を読み、動作を確認する
`composer.lock`・`package-lock.json`	依存ライブラリのバージョンをそろえる
`.env.example`	設定項目と初期値のひな形を示す
`.gitignore`	設定値や生成ファイルをGit管理から除く
`README.md`・`LICENSE`	使い方と利用条件を伝える

実際の.env、DBファイル、ログ、セッション、vendor/、node_modules/、ビルド結果は含めません。
依存ライブラリは取得した人がlockファイルを使って導入し、環境設定とDBも手元で作成します。
.gitignoreには、アプリ内の設定に加えて、リポジトリ全体で除外したい項目も記載しました。

このサンプルはMITライセンスで用意しました。
依存ライブラリにはそれぞれのライセンスがあるため、サンプルのライセンスと分けて扱います。

READMEだけで導入できるようにする

アプリのREADMEには、必要なPHP・Composer・Node.jsと、最初に実行するコマンドを書きます。
パスの基準は、composer.jsonとartisanがあるlaravel/learning-app/です。

以下はPHP・Composer・Node.js・npmを用意した後、LinuxやWSLのUbuntuのターミナルで初回セットアップする例です。

composer install
cp .env.example .env
php artisan key:generate
php -r "file_exists('database/database.sqlite') || touch('database/database.sqlite');"
php artisan migrate --no-interaction
npm ci
npm run build

composer installとnpm ciは依存ライブラリを取得するため、ネットワーク接続が必要です。
.envのコピーと鍵生成は初回用です。
設定済みのアプリに対して、既存の設定や鍵を上書きする手順としては使いません。

マイグレーションとビルドが完了したら、開発用サーバーを起動します。

php artisan serve --host=127.0.0.1 --port=8000

ブラウザーでhttp://127.0.0.1:8000/を開くと、ツール一覧を表示します。
Hello Worldは/helloと/hello/view、名前入力フォームは/learning/greetingで確認できます。
サンプルごとのURLと期待する動作もREADMEに並べました。

GitHubから取得して導入・動作を確認する

公開したファイルだけで導入できるかを確かめるため、GitHubから別フォルダーへ新しく取得します。

git clone https://github.com/ojichiku/php-samples.git
cd php-samples/laravel/learning-app

このフォルダーで先ほどの初回セットアップを実行し、続けて次のコマンドで依存要件とテストを確認します。

composer validate --strict
composer check-platform-reqs
php artisan test --compact

さらにnpm run buildで画面用のファイルを生成できるかを確認します。
ブラウザーでの操作確認は、アプリを起動してから別ターミナルで実行する手順として、READMEに分けて記載しました。

2026年11月1日にGitHubから新しく取得したコードで、依存導入、DBの初期化、ビルド、PHPテスト78件・394アサーションが成功しました。
ブラウザーでも、基礎サンプルは375・1280px幅、ツール画面は320・375・768・1280px幅で操作を確認しています。
スマホ実機や他のブラウザーでの動作確認は含みません。