PHP + Laravel マニュアル（VS Code / 初心者向け）

0. 全体像（最初に地図を持つ）

おすすめの選び方（Windows）

1. 必要なもの（用語と最低限）

2. 環境構築（Windows：おすすめ順）

2-A. Laravel Herd（いちばん簡単）

1. Herd をインストール（公式サイトから）
2. インストール後、PowerShell で確認：

   php -v
   composer -V

   （Herd により PHP が入っていれば php が動きます。）

2-B. Laravel Sail（Docker / WSL2）

1. WSL2（Ubuntuなど）を入れる（Windowsの標準機能）
2. Docker Desktop を入れ、WSL2 統合を有効にする
3. 以降の作業は基本的に WSL2 側のターミナル で行う（パスや権限でハマりにくい）

3. 新規プロジェクトを作る（2通り）

3-1. まず作業フォルダを作る（VS Codeで開く）

1. 例：C:\work\laravel-sample を作成
2. VS Code → File → Open Folder... で開く
3. VS Code → Terminal → New Terminal

3-2. Composer で作る（初心者はこれでOK）

# フォルダ直下で（例：C:\work）
composer create-project laravel/laravel my-app

3-3. Laravel Installer で作る（慣れたら）

Laravel 公式は「PHP / Composer / Laravel installer」の用意を前提に案内しています。

# Laravel installer を入れる（例）
composer global require laravel/installer

# 新規作成
laravel new my-app

4. 起動・動作確認（最初のゴール）

4-1. 開発サーバー起動（標準）

cd my-app
php artisan serve

ブラウザで http://127.0.0.1:8000 を開いて Laravel のトップが出ればOK。

4-2. フロントのビルド（必要になったら）

# 依存導入 → 開発ビルド
npm install
npm run dev

4-3. Sail の場合

# （プロジェクト直下）
./vendor/bin/sail up -d

※ Sail は Docker のコンテナを起動します。

5. VS Code 設定（最低限これだけ）

5-1. 入れる拡張機能

5-2. ワークスペース推奨（初心者向け）

6. デバッグ（Xdebug + VS Code）

6-1. VS Code 側：launch.json を作る

1. 左の「実行とデバッグ」 → 「launch.json を作成」
2. テンプレから Listen for Xdebug（または PHP Debug）を選ぶ

最小例（.vscode/launch.json）

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "${workspaceFolder}": "${workspaceFolder}"
      }
    }
  ]
}

6-2. PHP 側：Xdebug を有効化する（Herd の場合）

概念として必要になる設定（例：xdebug.mode / start_with_request / client_port など）

; 例：php.ini / xdebug.ini（場所は環境により異なる）
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

6-3. Sail（Docker）の場合：典型の考え方

1. VS Code は Listen for Xdebug を開始
2. コンテナ側の PHP に Xdebug を入れて debug を ON
3. pathMappings を「コンテナ内パス ↔ ワークスペース」に合わせる

7. リリース（本番配置）— まず「何をやるか」を固定する

7-1. “配布物” とは何か（Laravelの場合）

• ソース一式（通常は Git から取得）
• vendor/（Composer 依存で生成される：本番では composer install で作る）
• .env（本番設定：機密なので Git に入れない）

7-2. 本番の基本手順（超定番チェックリスト）

1. 本番の .env を用意（最低限）

   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=...（本番用）

2. 依存インストール（本番向け）

   composer install --no-dev --optimize-autoloader

   --no-dev：開発用依存を入れない（本番を軽く）
   --optimize-autoloader：オートロード最適化（本番向け）
3. アプリ最適化（代表）

   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   php artisan event:cache

   公式の Deployment で config:cache などの実行が推奨されています。
4. DB を使うなら migrate（本番は force）

   php artisan migrate --force

5. ストレージリンク（必要な場合）

   php artisan storage:link

7-3. 公開（ホスティング）の代表パターン

8. よくある詰まり（ここだけ見れば復帰できる）

8-1. composer が見つからない

• Composer が未インストール
• PATH が通っていない（再起動で直ることが多い）

8-2. php artisan serve は動くが、VS Code デバッグで止まらない

• Xdebug が有効な php.ini が違う（CLI と Web で別のことがある）
• VS Code が 9003 を待ち受けていない（Listen を押していない）
• Docker（Sail）の場合：pathMappings が合っていない

8-3. 本番で 500 エラー（画面真っ白）

• APP_DEBUG=false だと詳細が出ない → まずは ログ（storage/logs）を見る
• 権限（storage/, bootstrap/cache）
• キャッシュの作り直し（設定を変えたのに反映されない）

サンプル仕様：ユーザー検索（一覧）＋ユーザー編集（2画面構成）

1) 前提：users テーブル定義（この項目が存在すること）

2) ルーティング（URL と画面/処理の対応）

3) 画面仕様①：ユーザー一覧（検索＋結果）

3-1. 画面に表示されるもの

• 検索入力：ユーザー名の先頭文字（例：a）
• 検索ボタン：入力値で検索（GET /users?prefix=...）
• クリア（任意）：検索条件を外して全件（GET /users）
• 結果テーブル：該当ユーザーの一覧

3-2. 一覧テーブルの列（例）

3-3. 検索ルール

• 入力が空：全件（または「未検索」扱い）
• 入力がある：username LIKE '入力%' の前方一致
• 大文字/小文字：DB設定に依存（MySQLの照合順序など）

4) 画面仕様②：ユーザー編集（email / tel を更新）

4-1. 画面に表示されるもの

• 表示専用：id / username
• 編集可能：email / tel（要件どおり）
• 参考表示（任意）：address / update_at
• 保存ボタン：PUT /users/{id}
• 戻るボタン：一覧へ（検索条件があれば保持して戻すのが親切）

4-2. 更新ルール

• email はメール形式チェック（例：email バリデーション）
• tel は形式をゆるく（数字・+・-・空白程度） or 正規化して保存
• 更新成功：一覧へリダイレクトし、完了メッセージを表示
• 更新失敗：編集画面に戻し、エラーメッセージ表示

5) エラーハンドリング（最低限）

• 存在しない id：404（findOrFail 相当）
• バリデーションエラー：編集画面に戻して入力とエラーを表示
• DB更新失敗：編集画面にエラー表示（ログも残す）

Laravel（PHP）サンプル：ユーザー検索（一覧）＋ユーザー編集（2画面・パターンA）

1. 前提：users テーブル（必須カラム）

ユーザーテーブル（users）には、次の項目が存在するものとします。

2. 画面構成（2画面）

2-1. 画面①：ユーザー一覧（検索＋結果）

• 検索入力：prefix（usernameの先頭文字）
• 検索方法：前方一致（例：a → username LIKE 'a%'）
• 一覧表示列：username, email, tel, address
• 行クリック：usernameをクリックすると編集画面へ遷移（例：/users/2/edit）
• id, update_at は画面に表示しない

2-2. 画面②：ユーザー編集（email/telのみ編集）

• 表示専用：username, address
• 編集可能：email, tel
• 保存：PUT /users/{id}
• 更新成功：一覧へリダイレクト（PRG）＋成功メッセージ
• 更新失敗：編集画面に戻る＋入力保持＋エラーメッセージ

3. ルーティング（routes/web.php）

一覧・編集・更新の3つのルートを定義します。

<?php

use Illuminate\Support\Facades\Route;       // ルーティング定義に使う
use App\Http\Controllers\UserController;    // Controller を参照する

// 一覧（検索＋結果表示）
Route::get('/users', [UserController::class, 'index'])
    ->name('users.index');

// 編集画面（表示）
Route::get('/users/{id}/edit', [UserController::class, 'edit'])
    ->whereNumber('id') // id は数値のみ
    ->name('users.edit');

// 更新（email/tel の更新）
Route::put('/users/{id}', [UserController::class, 'update'])
    ->whereNumber('id') // id は数値のみ
    ->name('users.update');

4. ファイル分割（業務レベルの構成）

Controller直書きにせず、業務コードとして層を分けます。

routes/
  web.php

app/
  Http/
    Controllers/
      UserController.php
    Requests/
      UserSearchRequest.php
      UserUpdateRequest.php
  Services/
    UserService.php
    I18nService.php
  Repositories/
    Contracts/
      UserRepositoryInterface.php
      I18nRepositoryInterface.php
    Eloquent/
      UserRepository.php
      I18nRepository.php
  Dtos/
    UserListItemDto.php
    UserEditDto.php
    UserUpdateDto.php
  Models/
    User.php
    I18nMessage.php
  Exceptions/
    RepositoryException.php
    ServiceException.php
    AppMessageKeyException.php
  Support/
    I18n/
      I18n.php          (Facade/Helper)
      I18nKeys.php      (キー定数)
      LocaleResolver.php
  Providers/
    AppServiceProvider.php

resources/
  views/
    users/
      index.blade.php
      edit.blade.php

database/
  migrations/
    2026_02_16_000001_create_users_table.php
    2026_02_16_000002_create_i18n_messages_table.php

5. DB（SQLite）設定

5-1. .env（SQLite接続）

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:PLEASE_GENERATE
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/your-project/database/database.sqlite

5-2. Migration（usersテーブル作成）

<?php

use Illuminate\Database\Migrations\Migration; // マイグレーション基底クラス
use Illuminate\Database\Schema\Blueprint;      // テーブル定義に使う
use Illuminate\Support\Facades\Schema;         // Schemaビルダー

return new class extends Migration {

    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {

            $table->id(); // id（主キー / auto increment）

            $table->string('username', 100); // username（検索対象）
            $table->string('email', 255);    // email（編集対象）
            $table->string('tel', 50)->nullable(); // tel（編集対象 / null可）
            $table->string('address', 255)->nullable(); // address（表示用 / null可）

            // 要件：update_at（一般的な updated_at ではない）
            $table->timestamp('update_at')->nullable();

            $table->index('username');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

6. Entity（Eloquent Model）

Eloquentモデル（Entity相当）として app/Models/User.php を定義します。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';

    protected $fillable = [
        'username',
        'email',
        'tel',
        'address',
        'update_at',
    ];

    public $timestamps = false;
}

7. DTO（画面・層間のデータ受け渡し）

画面に不要な項目を混ぜないため、DTOで扱うカラムを明確にします。

7-1. UserListItemDto（一覧の1行分）

<?php

namespace App\Dtos;

class UserListItemDto
{
    public function __construct(
        public int $id,             // 画面表示はしないが、編集URL生成に必要
        public string $username,    // 一覧表示
        public string $email,       // 一覧表示
        public ?string $tel,        // 一覧表示（null可）
        public ?string $address     // 一覧表示（null可）
    ) {}
}

7-2. UserEditDto（編集画面表示用）

<?php

namespace App\Dtos;

class UserEditDto
{
    public function __construct(
        public int $id,
        public string $username,
        public string $email,
        public ?string $tel,
        public ?string $address
    ) {}
}

7-3. UserUpdateDto（更新入力用）

<?php

namespace App\Dtos;

class UserUpdateDto
{
    public function __construct(
        public int $id,
        public string $email,
        public ?string $tel
    ) {}
}

8. 例外（層ごとに例外を分ける）

Repository層とService層で例外クラスを分け、責務を明確化します。

8-1. RepositoryException

<?php

namespace App\Exceptions;

use RuntimeException;

class RepositoryException extends RuntimeException
{
}

8-2. ServiceException

<?php

namespace App\Exceptions;

use RuntimeException;

class ServiceException extends RuntimeException
{
}

8-3. AppMessageKeyException（メッセージ文字列は禁止：キーだけを運ぶ）

<?php

namespace App\Exceptions;

use RuntimeException;

// 「文字列」ではなく「メッセージキー」を保持する例外
class AppMessageKeyException extends RuntimeException
{
    public function __construct(
        public string $messageKey,
        int $code = 0,
        ?\Throwable $previous = null
    ) {
        // 例外メッセージ欄にもキーだけを入れる（ログ用途）
        parent::__construct($messageKey, $code, $previous);
    }
}

9. Repository（Interface + 実装）

9-1. UserRepositoryInterface（契約）

<?php

namespace App\Repositories\Contracts;

use App\Dtos\UserEditDto;
use App\Dtos\UserListItemDto;
use App\Dtos\UserUpdateDto;

interface UserRepositoryInterface
{
    /** @return UserListItemDto[] */
    public function searchByUsernamePrefix(?string $prefix, int $limit = 50): array;

    public function findEditDtoById(int $id): ?UserEditDto;

    public function updateContact(UserUpdateDto $dto): bool;
}

9-2. UserRepository（Eloquent実装）※例外は「キー」で投げる

<?php

namespace App\Repositories\Eloquent;

use App\Dtos\UserEditDto;
use App\Dtos\UserListItemDto;
use App\Dtos\UserUpdateDto;
use App\Exceptions\AppMessageKeyException;   // 文字列禁止：キー例外
use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Facades\Log;

class UserRepository implements UserRepositoryInterface
{
    public function searchByUsernamePrefix(?string $prefix, int $limit = 50): array
    {
        try {
            $query = User::query()
                ->select(['id', 'username', 'email', 'tel', 'address']);

            if ($prefix !== null && $prefix !== '') {
                $query->where('username', 'like', $prefix . '%');
            }

            $rows = $query->orderBy('username')->limit($limit)->get();

            $dtos = [];
            foreach ($rows as $u) {
                $dtos[] = new UserListItemDto(
                    id: (int)$u->id,
                    username: (string)$u->username,
                    email: (string)$u->email,
                    tel: $u->tel !== null ? (string)$u->tel : null,
                    address: $u->address !== null ? (string)$u->address : null
                );
            }
            return $dtos;

        } catch (\Throwable $e) {
            Log::error('[UserRepository] searchByUsernamePrefix failed', [
                'prefix' => $prefix,
                'limit' => $limit,
                'error' => $e->getMessage(),
            ]);

            // 文字列を禁止：キーだけ投げる
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_QUERY_FAILED, 0, $e);
        }
    }

    public function findEditDtoById(int $id): ?UserEditDto
    {
        try {
            $u = User::query()
                ->select(['id', 'username', 'email', 'tel', 'address'])
                ->where('id', $id)
                ->first();

            if ($u === null) {
                return null;
            }

            return new UserEditDto(
                id: (int)$u->id,
                username: (string)$u->username,
                email: (string)$u->email,
                tel: $u->tel !== null ? (string)$u->tel : null,
                address: $u->address !== null ? (string)$u->address : null
            );

        } catch (\Throwable $e) {
            Log::error('[UserRepository] findEditDtoById failed', [
                'id' => $id,
                'error' => $e->getMessage(),
            ]);

            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_QUERY_FAILED, 0, $e);
        }
    }

    public function updateContact(UserUpdateDto $dto): bool
    {
        try {
            $u = User::query()->where('id', $dto->id)->first();
            if ($u === null) {
                return false;
            }

            $u->email = $dto->email;
            $u->tel = $dto->tel;
            $u->update_at = now();
            $u->save();

            return true;

        } catch (\Throwable $e) {
            Log::error('[UserRepository] updateContact failed', [
                'id' => $dto->id,
                'error' => $e->getMessage(),
            ]);

            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_UPDATE_FAILED, 0, $e);
        }
    }
}

10. Service（業務ロジック層）

Serviceも「文字列禁止」。例外はキーで受けて上位へ伝播します。

<?php

namespace App\Services;

use App\Dtos\UserEditDto;
use App\Dtos\UserUpdateDto;
use App\Exceptions\AppMessageKeyException;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Facades\Log;

class UserService
{
    public function __construct(
        private readonly UserRepositoryInterface $userRepo
    ) {}

    public function search(?string $prefix): array
    {
        try {
            return $this->userRepo->searchByUsernamePrefix($prefix, 50);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] search failed', ['key' => $e->messageKey]);
            throw $e; // キーのまま上位へ
        } catch (\Throwable $e) {
            Log::error('[UserService] search unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }

    public function getEditDto(int $id): ?UserEditDto
    {
        try {
            return $this->userRepo->findEditDtoById($id);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] getEditDto failed', ['key' => $e->messageKey]);
            throw $e;
        } catch (\Throwable $e) {
            Log::error('[UserService] getEditDto unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }

    public function updateContact(UserUpdateDto $dto): bool
    {
        try {
            return $this->userRepo->updateContact($dto);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] updateContact failed', ['key' => $e->messageKey]);
            throw $e;
        } catch (\Throwable $e) {
            Log::error('[UserService] updateContact unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }
}

11. DI（Repositoryのバインド）

Interfaceと実装を結びつけ、Controller/Service側は契約に依存します。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\Contracts\UserRepositoryInterface;
use App\Repositories\Eloquent\UserRepository;

use App\Repositories\Contracts\I18nRepositoryInterface;
use App\Repositories\Eloquent\I18nRepository;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
        $this->app->bind(I18nRepositoryInterface::class, I18nRepository::class);
    }

    public function boot(): void
    {
        //
    }
}

12. FormRequest（入力バリデーション）

バリデーションメッセージも「文字列禁止」。キーで返し、I18nで解決します。

12-1. UserSearchRequest（検索）

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UserSearchRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'prefix' => ['nullable', 'string', 'max:50'],
        ];
    }

    // 文字列禁止：メッセージはキーを返す
    public function messages(): array
    {
        return [
            'prefix.string' => \App\Support\I18n\I18nKeys::V_PREFIX_STRING,
            'prefix.max'    => \App\Support\I18n\I18nKeys::V_PREFIX_MAX,
        ];
    }

    // 文字列禁止：属性名もキーにする
    public function attributes(): array
    {
        return [
            'prefix' => \App\Support\I18n\I18nKeys::A_PREFIX,
        ];
    }
}

12-2. UserUpdateRequest（更新）

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UserUpdateRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email', 'max:255'],
            'tel'   => ['nullable', 'string', 'max:50'],
        ];
    }

    public function messages(): array
    {
        return [
            'email.required' => \App\Support\I18n\I18nKeys::V_EMAIL_REQUIRED,
            'email.email'    => \App\Support\I18n\I18nKeys::V_EMAIL_EMAIL,
            'email.max'      => \App\Support\I18n\I18nKeys::V_EMAIL_MAX,
            'tel.max'        => \App\Support\I18n\I18nKeys::V_TEL_MAX,
        ];
    }

    public function attributes(): array
    {
        return [
            'email' => \App\Support\I18n\I18nKeys::A_EMAIL,
            'tel'   => \App\Support\I18n\I18nKeys::A_TEL,
        ];
    }
}

13. Controller（HTTP責務：PRG、404、例外、フラッシュメッセージ）

Controllerは「キー」だけ受け取り、表示直前に I18n で文字列へ解決します。

<?php

namespace App\Http\Controllers;

use App\Dtos\UserUpdateDto;
use App\Http\Requests\UserSearchRequest;
use App\Http\Requests\UserUpdateRequest;
use App\Services\UserService;
use App\Support\I18n\I18n;                 // 文字列解決サービス
use App\Support\I18n\I18nKeys;             // キー定数
use App\Exceptions\AppMessageKeyException; // キー例外
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;
use Illuminate\Support\Facades\Log;

class UserController extends Controller
{
    public function __construct(
        private readonly UserService $userService
    ) {}

    public function index(UserSearchRequest $request): View
    {
        $prefix = $request->input('prefix');

        try {
            $users = $this->userService->search($prefix);

            return view('users.index', [
                'prefix' => $prefix,
                'users'  => $users,
            ]);

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] index failed', [
                'key'    => $e->messageKey,
                'prefix' => $prefix,
            ]);

            return view('users.index', [
                'prefix'      => $prefix,
                'users'       => [],
                'globalError' => I18n::t($e->messageKey), // 表示直前に解決
            ]);

        } catch (\Throwable $e) {

            Log::error('[UserController] index unexpected', [
                'prefix' => $prefix,
                'error'  => $e->getMessage(),
            ]);

            return view('users.index', [
                'prefix'      => $prefix,
                'users'       => [],
                'globalError' => I18n::t(I18nKeys::E_UNEXPECTED),
            ]);
        }
    }

    public function edit(int $id): View
    {
        try {
            $dto = $this->userService->getEditDto($id);

            if ($dto === null) {
                abort(404, I18n::t(I18nKeys::E_USER_NOT_FOUND));
            }

            return view('users.edit', [
                'user' => $dto,
            ]);

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] edit failed', [
                'id'  => $id,
                'key' => $e->messageKey,
            ]);

            abort(500, I18n::t($e->messageKey));

        } catch (\Throwable $e) {

            Log::error('[UserController] edit unexpected', [
                'id'    => $id,
                'error' => $e->getMessage(),
            ]);

            abort(500, I18n::t(I18nKeys::E_UNEXPECTED));
        }
    }

    public function update(UserUpdateRequest $request, int $id): RedirectResponse
    {
        $email = $request->input('email');
        $tel   = $request->input('tel');

        try {
            $ok = $this->userService->updateContact(
                new UserUpdateDto(id: $id, email: $email, tel: $tel)
            );

            if (!$ok) {
                return redirect()
                    ->route('users.index')
                    ->with('error', I18n::t(I18nKeys::E_USER_NOT_FOUND));
            }

            return redirect()
                ->route('users.index')
                ->with('success', I18n::t(I18nKeys::S_USER_UPDATED));

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] update failed', [
                'id'  => $id,
                'key' => $e->messageKey,
            ]);

            return back()
                ->withInput()
                ->with('error', I18n::t($e->messageKey));

        } catch (\Throwable $e) {

            Log::error('[UserController] update unexpected', [
                'id'    => $id,
                'error' => $e->getMessage(),
            ]);

            return back()
                ->withInput()
                ->with('error', I18n::t(I18nKeys::E_UNEXPECTED));
        }
    }
}

14. Blade（画面テンプレート：2画面）

Bladeも「文字列禁止」。固定文言はすべて I18n のキー参照にします。

14-1. 一覧画面（resources/views/users/index.blade.php）

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_INDEX) }}</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body{ font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans JP", sans-serif; margin: 24px; }
    .box{ border: 1px solid #ddd; padding: 16px; border-radius: 8px; margin-bottom: 16px; }
    .ok{ border-left: 6px solid #22c55e; background: #f0fdf4; padding: 12px; border-radius: 8px; }
    .warn{ border-left: 6px solid #f59e0b; background: #fffbeb; padding: 12px; border-radius: 8px; }
    .err{ border-left: 6px solid #ef4444; background: #fef2f2; padding: 12px; border-radius: 8px; }
    table{ width: 100%; border-collapse: collapse; }
    th, td{ border-bottom: 1px solid #eee; padding: 10px; text-align: left; }
    a{ color: #2563eb; text-decoration: none; }
    a:hover{ text-decoration: underline; }
    .muted{ color: #666; font-size: 12px; }
    input{ padding: 8px 10px; width: 240px; }
    button{ padding: 8px 12px; cursor: pointer; }
  </style>
</head>
<body>

  <h1>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_INDEX) }}</h1>

  @if(session('success'))
    <div class="ok">{{ session('success') }}</div>
  @endif

  @if(session('error'))
    <div class="err">{{ session('error') }}</div>
  @endif

  @if(!empty($globalError))
    <div class="err">{{ $globalError }}</div>
  @endif

  <div class="box">
    <form method="GET" action="{{ route('users.index') }}">

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_PREFIX) }}
        <input
          type="text"
          name="prefix"
          value="{{ old('prefix', $prefix) }}"
          placeholder="{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::P_PREFIX) }}"
        >
      </label>

      <button type="submit">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_SEARCH) }}</button>

      <a href="{{ route('users.index') }}" class="muted" style="margin-left:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_CLEAR) }}
      </a>

      @error('prefix')
        {{-- バリデーションが返す $message は「キー」なので、I18nで解決して表示 --}}
        <div class="warn" style="margin-top:10px;">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_PREFIX_RULE) }}
      </div>

    </form>
  </div>

  <div class="box">
    <h2>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_LIST) }}</h2>

    @if(empty($users) || count($users) === 0)
      <div class="warn">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_NO_RESULT) }}</div>
    @else
      <table>
        <thead>
          <tr>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_USERNAME) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_EMAIL) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_TEL) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_ADDRESS) }}</th>
          </tr>
        </thead>
        <tbody>
          @foreach($users as $u)
            <tr>
              <td>
                <a href="{{ route('users.edit', ['id' => $u->id]) }}">{{ $u->username }}</a>
              </td>
              <td>{{ $u->email }}</td>
              <td>{{ $u->tel ?? '' }}</td>
              <td>{{ $u->address ?? '' }}</td>
            </tr>
          @endforeach
        </tbody>
      </table>

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_CLICK_TO_EDIT) }}
      </div>
    @endif
  </div>

</body>
</html>

14-2. 編集画面（resources/views/users/edit.blade.php）

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_EDIT) }}</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body{ font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans JP", sans-serif; margin: 24px; }
    .box{ border: 1px solid #ddd; padding: 16px; border-radius: 8px; margin-bottom: 16px; max-width: 640px; }
    .warn{ border-left: 6px solid #f59e0b; background: #fffbeb; padding: 12px; border-radius: 8px; }
    .err{ border-left: 6px solid #ef4444; background: #fef2f2; padding: 12px; border-radius: 8px; }
    label{ display:block; margin-top: 12px; }
    input{ padding: 8px 10px; width: 100%; box-sizing: border-box; }
    button{ padding: 8px 12px; cursor: pointer; margin-top: 14px; }
    .muted{ color: #666; font-size: 12px; }
  </style>
</head>
<body>

  <h1>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_EDIT) }}</h1>

  @if(session('error'))
    <div class="err">{{ session('error') }}</div>
  @endif

  <div class="box">

    <div>
      <div class="muted">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_USERNAME) }}</div>
      <div><b>{{ $user->username }}</b></div>
    </div>

    <div style="margin-top:12px;">
      <div class="muted">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_ADDRESS) }}</div>
      <div>{{ $user->address ?? '' }}</div>
    </div>

    <hr style="margin: 16px 0; border: none; border-top: 1px solid #eee;">

    <form method="POST" action="{{ route('users.update', ['id' => $user->id]) }}">
      @csrf
      @method('PUT')

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_EMAIL) }}
        <input type="text" name="email" value="{{ old('email', $user->email) }}">
      </label>
      @error('email')
        <div class="warn">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_TEL) }}
        <input type="text" name="tel" value="{{ old('tel', $user->tel) }}">
      </label>
      @error('tel')
        <div class="warn">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <button type="submit">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_SAVE) }}</button>

      <a href="{{ route('users.index') }}" style="margin-left:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_BACK_TO_LIST) }}
      </a>

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_EDIT_RULE) }}
      </div>

    </form>
  </div>

</body>
</html>

15. 多言語化（「ソース内に文字列を一切ハードコードしない」方式）

15-1. 外部多言語辞書（DBテーブル：i18n_messages）

翻訳文言は DBに保持します（SQLiteでも可）。
アプリは キー と ロケール から文字列を取得し、表示します。
※ DBの中身（翻訳文章）は「運用データ」であり、ソースコードには含めません（要件：文字列ハードコード禁止）。

15-2. Migration（i18n_messages テーブル）

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {

    public function up(): void
    {
        Schema::create('i18n_messages', function (Blueprint $table) {

            $table->id();

            // 例: ja / en / th など
            $table->string('locale', 10);

            // 例: ui.titles.user_index / errors.db_query_failed など
            $table->string('msg_key', 200);

            // 実際の表示文字列（※ソースには置かない：DBデータとして運用）
            $table->text('msg_value');

            // 重複防止
            $table->unique(['locale', 'msg_key']);

            // 参照が多いので索引
            $table->index(['locale', 'msg_key']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('i18n_messages');
    }
};

15-3. Entity（I18nMessage Model）

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class I18nMessage extends Model
{
    protected $table = 'i18n_messages';

    protected $fillable = [
        'locale',
        'msg_key',
        'msg_value',
    ];

    public $timestamps = false;
}

15-4. I18nKeys（キーの定数化：文字列禁止のため）

「キー文字列」すら散らばらないように、キーは定数で一元管理します。
※キーそのものは文言ではないため、ここでは許可（ただし “定数化” して散らばりを防止）。

<?php

namespace App\Support\I18n;

final class I18nKeys
{
    // titles
    public const T_USER_INDEX   = 'ui.titles.user_index';
    public const T_USER_LIST    = 'ui.titles.user_list';
    public const T_USER_EDIT    = 'ui.titles.user_edit';

    // labels
    public const L_PREFIX   = 'ui.labels.prefix';
    public const L_USERNAME = 'ui.labels.username';
    public const L_EMAIL    = 'ui.labels.email';
    public const L_TEL      = 'ui.labels.tel';
    public const L_ADDRESS  = 'ui.labels.address';

    // placeholders
    public const P_PREFIX = 'ui.placeholders.prefix';

    // actions
    public const A_SEARCH       = 'ui.actions.search';
    public const A_CLEAR        = 'ui.actions.clear';
    public const A_SAVE         = 'ui.actions.save';
    public const A_BACK_TO_LIST = 'ui.actions.back_to_list';

    // columns
    public const C_USERNAME = 'ui.columns.username';
    public const C_EMAIL    = 'ui.columns.email';
    public const C_TEL      = 'ui.columns.tel';
    public const C_ADDRESS  = 'ui.columns.address';

    // notes
    public const N_PREFIX_RULE   = 'ui.notes.prefix_rule';
    public const N_NO_RESULT     = 'ui.notes.no_result';
    public const N_CLICK_TO_EDIT = 'ui.notes.click_to_edit';
    public const N_EDIT_RULE     = 'ui.notes.edit_rule';

    // success
    public const S_USER_UPDATED = 'success.user_updated';

    // errors
    public const E_USER_NOT_FOUND    = 'errors.user_not_found';
    public const E_DB_QUERY_FAILED   = 'errors.db_query_failed';
    public const E_DB_UPDATE_FAILED  = 'errors.db_update_failed';
    public const E_UNEXPECTED        = 'errors.unexpected';

    // validation attributes (属性名)
    public const A_PREFIX = 'validation.attributes.prefix';
    public const A_EMAIL  = 'validation.attributes.email';
    public const A_TEL    = 'validation.attributes.tel';

    // validation rules (メッセージ)
    public const V_PREFIX_STRING  = 'validation.rules.prefix.string';
    public const V_PREFIX_MAX     = 'validation.rules.prefix.max';
    public const V_EMAIL_REQUIRED = 'validation.rules.email.required';
    public const V_EMAIL_EMAIL    = 'validation.rules.email.email';
    public const V_EMAIL_MAX      = 'validation.rules.email.max';
    public const V_TEL_MAX        = 'validation.rules.tel.max';
}

15-5. I18nRepository（DBから取得：文字列はDBデータのみ）

<?php

namespace App\Repositories\Contracts;

interface I18nRepositoryInterface
{
    // キーとロケールでメッセージを取得（無ければ null）
    public function findValue(string $locale, string $msgKey): ?string;
}

<?php

namespace App\Repositories\Eloquent;

use App\Models\I18nMessage;
use App\Repositories\Contracts\I18nRepositoryInterface;

class I18nRepository implements I18nRepositoryInterface
{
    public function findValue(string $locale, string $msgKey): ?string
    {
        $row = I18nMessage::query()
            ->select(['msg_value'])
            ->where('locale', $locale)
            ->where('msg_key', $msgKey)
            ->first();

        return $row ? (string)$row->msg_value : null;
    }
}

15-6. I18nService / Helper（キーから文字列を解決）

表示直前に I18n::t(KEY) を呼び、DB辞書から文字列を解決します。
もし辞書に存在しない場合は「キーをそのまま返す」などの運用ポリシーにできます（※ここでは例示のみ。文言は一切埋め込まない）。

<?php

namespace App\Services;

use App\Repositories\Contracts\I18nRepositoryInterface;
use Illuminate\Support\Facades\Cache;

class I18nService
{
    public function __construct(
        private readonly I18nRepositoryInterface $repo
    ) {}

    public function translate(string $locale, string $key): string
    {
        // 高頻度アクセスなのでキャッシュ（キー+ロケール単位）
        $cacheKey = 'i18n:' . $locale . ':' . $key;

        return Cache::remember($cacheKey, 300, function () use ($locale, $key) {

            // DBから取得（文字列はDBデータのみ）
            $val = $this->repo->findValue($locale, $key);

            // 無い場合：キーを返す（文字列を埋め込まないためのフォールバック）
            return $val ?? $key;
        });
    }
}

<?php

namespace App\Support\I18n;

use App\Services\I18nService;

// Blade/Controller から呼びやすい静的ヘルパ
final class I18n
{
    public static function t(string $key): string
    {
        // ロケール決定（例：config/app.php, session, header 等）
        $locale = app(LocaleResolver::class)->resolve();

        return app(I18nService::class)->translate($locale, $key);
    }
}

15-7. LocaleResolver（ロケール決定）

<?php

namespace App\Support\I18n;

use Illuminate\Http\Request;

class LocaleResolver
{
    public function __construct(
        private readonly Request $request
    ) {}

    public function resolve(): string
    {
        // 例：?lang=ja / ?lang=en を優先（業務では session / user設定 / header 等に合わせる）
        $lang = (string)$this->request->query('lang', '');

        // 許可された言語だけに限定（値は config へ寄せることが多い）
        if ($lang === 'ja' || $lang === 'en') {
            return $lang;
        }

        // 既定は ja（※文言ではないのでOK）
        return 'ja';
    }
}

15-8. 「バリデーション文言がキーのまま」になる点の扱い（この仕様での正解）

• FormRequest の messages() で返す値は「文字列」ではなく「キー」にする
• Blade側の @error では $message をそのまま表示せず、I18n::t($message) で解決して表示する
• 属性名（:attribute）を組み立てる場合は、I18n側で置換する拡張を入れる（業務では {attribute} 置換など）

16. 実行手順（SQLiteで起動）

# 1) SQLite DBファイルを作成（空でOK）
touch database/database.sqlite

# 2) .env の DB_DATABASE をプロジェクトの絶対パスに合わせる

# 3) マイグレーション実行
php artisan migrate

# 4) i18n_messages に翻訳データを投入（※運用データとして投入。ソースに埋め込まない）
#    例：CSVインポート、管理画面、別DBから同期、翻訳サービス連携など

# 5) 開発サーバ起動
php artisan serve

# 6) ブラウザでアクセス（例：?lang=ja / ?lang=en）
# http://localhost:8000/users?lang=ja
# http://localhost:8000/users?lang=en

Laravel（PHP）サンプル：ユーザー検索（一覧）＋ユーザー編集（2画面・パターンA）

1. 前提：users テーブル（必須カラム）

ユーザーテーブル（users）には、次の項目が存在するものとします。

2. 画面構成（2画面）

2-1. 画面①：ユーザー一覧（検索＋結果）

• 検索入力：prefix（usernameの先頭文字）
• 検索方法：前方一致（例：a → username LIKE 'a%'）
• 一覧表示列：username, email, tel, address
• 行クリック：usernameをクリックすると編集画面へ遷移（例：/users/2/edit）
• id, update_at は画面に表示しない

2-2. 画面②：ユーザー編集（email/telのみ編集）

• 表示専用：username, address
• 編集可能：email, tel
• 保存：PUT /users/{id}
• 更新成功：一覧へリダイレクト（PRG）＋成功メッセージ
• 更新失敗：編集画面に戻る＋入力保持＋エラーメッセージ

3. ルーティング（routes/web.php）

一覧・編集・更新の3つのルートを定義します。

<?php

use Illuminate\Support\Facades\Route;       // ルーティング定義に使う
use App\Http\Controllers\UserController;    // Controller を参照する

// 一覧（検索＋結果表示）
Route::get('/users', [UserController::class, 'index'])
    ->name('users.index');

// 編集画面（表示）
Route::get('/users/{id}/edit', [UserController::class, 'edit'])
    ->whereNumber('id') // id は数値のみ
    ->name('users.edit');

// 更新（email/tel の更新）
Route::put('/users/{id}', [UserController::class, 'update'])
    ->whereNumber('id') // id は数値のみ
    ->name('users.update');

4. ファイル分割（業務レベルの構成）

Controller直書きにせず、業務コードとして層を分けます。

routes/
  web.php

app/
  Http/
    Controllers/
      UserController.php
    Requests/
      UserSearchRequest.php
      UserUpdateRequest.php
  Services/
    UserService.php
    I18nService.php
  Repositories/
    Contracts/
      UserRepositoryInterface.php
      I18nRepositoryInterface.php
    Eloquent/
      UserRepository.php
      I18nRepository.php
  Dtos/
    UserListItemDto.php
    UserEditDto.php
    UserUpdateDto.php
  Models/
    User.php
    I18nMessage.php
  Exceptions/
    RepositoryException.php
    ServiceException.php
    AppMessageKeyException.php
  Support/
    I18n/
      I18n.php          (Facade/Helper)
      I18nKeys.php      (キー定数)
      LocaleResolver.php
  Providers/
    AppServiceProvider.php

resources/
  views/
    users/
      index.blade.php
      edit.blade.php

database/
  migrations/
    2026_02_16_000001_create_users_table.php
    2026_02_16_000002_create_i18n_messages_table.php

5. DB（SQLite）設定

5-1. .env（SQLite接続）

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:PLEASE_GENERATE
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/your-project/database/database.sqlite

5-2. Migration（usersテーブル作成）

<?php

use Illuminate\Database\Migrations\Migration; // マイグレーション基底クラス
use Illuminate\Database\Schema\Blueprint;      // テーブル定義に使う
use Illuminate\Support\Facades\Schema;         // Schemaビルダー

return new class extends Migration {

    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {

            $table->id(); // id（主キー / auto increment）

            $table->string('username', 100); // username（検索対象）
            $table->string('email', 255);    // email（編集対象）
            $table->string('tel', 50)->nullable(); // tel（編集対象 / null可）
            $table->string('address', 255)->nullable(); // address（表示用 / null可）

            // 要件：update_at（一般的な updated_at ではない）
            $table->timestamp('update_at')->nullable();

            $table->index('username');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

6. Entity（Eloquent Model）

Eloquentモデル（Entity相当）として app/Models/User.php を定義します。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';

    protected $fillable = [
        'username',
        'email',
        'tel',
        'address',
        'update_at',
    ];

    public $timestamps = false;
}

7. DTO（画面・層間のデータ受け渡し）

画面に不要な項目を混ぜないため、DTOで扱うカラムを明確にします。

7-1. UserListItemDto（一覧の1行分）

<?php

namespace App\Dtos;

class UserListItemDto
{
    public function __construct(
        public int $id,             // 画面表示はしないが、編集URL生成に必要
        public string $username,    // 一覧表示
        public string $email,       // 一覧表示
        public ?string $tel,        // 一覧表示（null可）
        public ?string $address     // 一覧表示（null可）
    ) {}
}

7-2. UserEditDto（編集画面表示用）

<?php

namespace App\Dtos;

class UserEditDto
{
    public function __construct(
        public int $id,
        public string $username,
        public string $email,
        public ?string $tel,
        public ?string $address
    ) {}
}

7-3. UserUpdateDto（更新入力用）

<?php

namespace App\Dtos;

class UserUpdateDto
{
    public function __construct(
        public int $id,
        public string $email,
        public ?string $tel
    ) {}
}

8. 例外（層ごとに例外を分ける）

Repository層とService層で例外クラスを分け、責務を明確化します。

8-1. RepositoryException

<?php

namespace App\Exceptions;

use RuntimeException;

class RepositoryException extends RuntimeException
{
}

8-2. ServiceException

<?php

namespace App\Exceptions;

use RuntimeException;

class ServiceException extends RuntimeException
{
}

8-3. AppMessageKeyException（メッセージ文字列は禁止：キーだけを運ぶ）

<?php

namespace App\Exceptions;

use RuntimeException;

// 「文字列」ではなく「メッセージキー」を保持する例外
class AppMessageKeyException extends RuntimeException
{
    public function __construct(
        public string $messageKey,
        int $code = 0,
        ?\Throwable $previous = null
    ) {
        // 例外メッセージ欄にもキーだけを入れる（ログ用途）
        parent::__construct($messageKey, $code, $previous);
    }
}

9. Repository（Interface + 実装）

9-1. UserRepositoryInterface（契約）

<?php

namespace App\Repositories\Contracts;

use App\Dtos\UserEditDto;
use App\Dtos\UserListItemDto;
use App\Dtos\UserUpdateDto;

interface UserRepositoryInterface
{
    /** @return UserListItemDto[] */
    public function searchByUsernamePrefix(?string $prefix, int $limit = 50): array;

    public function findEditDtoById(int $id): ?UserEditDto;

    public function updateContact(UserUpdateDto $dto): bool;
}

9-2. UserRepository（Eloquent実装）※例外は「キー」で投げる

<?php

namespace App\Repositories\Eloquent;

use App\Dtos\UserEditDto;
use App\Dtos\UserListItemDto;
use App\Dtos\UserUpdateDto;
use App\Exceptions\AppMessageKeyException;   // 文字列禁止：キー例外
use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Facades\Log;

class UserRepository implements UserRepositoryInterface
{
    public function searchByUsernamePrefix(?string $prefix, int $limit = 50): array
    {
        try {
            $query = User::query()
                ->select(['id', 'username', 'email', 'tel', 'address']);

            if ($prefix !== null && $prefix !== '') {
                $query->where('username', 'like', $prefix . '%');
            }

            $rows = $query->orderBy('username')->limit($limit)->get();

            $dtos = [];
            foreach ($rows as $u) {
                $dtos[] = new UserListItemDto(
                    id: (int)$u->id,
                    username: (string)$u->username,
                    email: (string)$u->email,
                    tel: $u->tel !== null ? (string)$u->tel : null,
                    address: $u->address !== null ? (string)$u->address : null
                );
            }
            return $dtos;

        } catch (\Throwable $e) {
            Log::error('[UserRepository] searchByUsernamePrefix failed', [
                'prefix' => $prefix,
                'limit' => $limit,
                'error' => $e->getMessage(),
            ]);

            // 文字列を禁止：キーだけ投げる
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_QUERY_FAILED, 0, $e);
        }
    }

    public function findEditDtoById(int $id): ?UserEditDto
    {
        try {
            $u = User::query()
                ->select(['id', 'username', 'email', 'tel', 'address'])
                ->where('id', $id)
                ->first();

            if ($u === null) {
                return null;
            }

            return new UserEditDto(
                id: (int)$u->id,
                username: (string)$u->username,
                email: (string)$u->email,
                tel: $u->tel !== null ? (string)$u->tel : null,
                address: $u->address !== null ? (string)$u->address : null
            );

        } catch (\Throwable $e) {
            Log::error('[UserRepository] findEditDtoById failed', [
                'id' => $id,
                'error' => $e->getMessage(),
            ]);

            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_QUERY_FAILED, 0, $e);
        }
    }

    public function updateContact(UserUpdateDto $dto): bool
    {
        try {
            $u = User::query()->where('id', $dto->id)->first();
            if ($u === null) {
                return false;
            }

            $u->email = $dto->email;
            $u->tel = $dto->tel;
            $u->update_at = now();
            $u->save();

            return true;

        } catch (\Throwable $e) {
            Log::error('[UserRepository] updateContact failed', [
                'id' => $dto->id,
                'error' => $e->getMessage(),
            ]);

            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_DB_UPDATE_FAILED, 0, $e);
        }
    }
}

10. Service（業務ロジック層）

Serviceも「文字列禁止」。例外はキーで受けて上位へ伝播します。

<?php

namespace App\Services;

use App\Dtos\UserEditDto;
use App\Dtos\UserUpdateDto;
use App\Exceptions\AppMessageKeyException;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Facades\Log;

class UserService
{
    public function __construct(
        private readonly UserRepositoryInterface $userRepo
    ) {}

    public function search(?string $prefix): array
    {
        try {
            return $this->userRepo->searchByUsernamePrefix($prefix, 50);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] search failed', ['key' => $e->messageKey]);
            throw $e; // キーのまま上位へ
        } catch (\Throwable $e) {
            Log::error('[UserService] search unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }

    public function getEditDto(int $id): ?UserEditDto
    {
        try {
            return $this->userRepo->findEditDtoById($id);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] getEditDto failed', ['key' => $e->messageKey]);
            throw $e;
        } catch (\Throwable $e) {
            Log::error('[UserService] getEditDto unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }

    public function updateContact(UserUpdateDto $dto): bool
    {
        try {
            return $this->userRepo->updateContact($dto);
        } catch (AppMessageKeyException $e) {
            Log::warning('[UserService] updateContact failed', ['key' => $e->messageKey]);
            throw $e;
        } catch (\Throwable $e) {
            Log::error('[UserService] updateContact unexpected', ['error' => $e->getMessage()]);
            throw new AppMessageKeyException(\App\Support\I18n\I18nKeys::E_UNEXPECTED, 0, $e);
        }
    }
}

11. DI（Repositoryのバインド）

Interfaceと実装を結びつけ、Controller/Service側は契約に依存します。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\Contracts\UserRepositoryInterface;
use App\Repositories\Eloquent\UserRepository;

use App\Repositories\Contracts\I18nRepositoryInterface;
use App\Repositories\Eloquent\I18nRepository;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
        $this->app->bind(I18nRepositoryInterface::class, I18nRepository::class);
    }

    public function boot(): void
    {
        //
    }
}

12. FormRequest（入力バリデーション）

バリデーションメッセージも「文字列禁止」。キーで返し、I18nで解決します。

12-1. UserSearchRequest（検索）

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UserSearchRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'prefix' => ['nullable', 'string', 'max:50'],
        ];
    }

    // 文字列禁止：メッセージはキーを返す
    public function messages(): array
    {
        return [
            'prefix.string' => \App\Support\I18n\I18nKeys::V_PREFIX_STRING,
            'prefix.max'    => \App\Support\I18n\I18nKeys::V_PREFIX_MAX,
        ];
    }

    // 文字列禁止：属性名もキーにする
    public function attributes(): array
    {
        return [
            'prefix' => \App\Support\I18n\I18nKeys::A_PREFIX,
        ];
    }
}

12-2. UserUpdateRequest（更新）

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class UserUpdateRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email', 'max:255'],
            'tel'   => ['nullable', 'string', 'max:50'],
        ];
    }

    public function messages(): array
    {
        return [
            'email.required' => \App\Support\I18n\I18nKeys::V_EMAIL_REQUIRED,
            'email.email'    => \App\Support\I18n\I18nKeys::V_EMAIL_EMAIL,
            'email.max'      => \App\Support\I18n\I18nKeys::V_EMAIL_MAX,
            'tel.max'        => \App\Support\I18n\I18nKeys::V_TEL_MAX,
        ];
    }

    public function attributes(): array
    {
        return [
            'email' => \App\Support\I18n\I18nKeys::A_EMAIL,
            'tel'   => \App\Support\I18n\I18nKeys::A_TEL,
        ];
    }
}

13. Controller（HTTP責務：PRG、404、例外、フラッシュメッセージ）

Controllerは「キー」だけ受け取り、表示直前に I18n で文字列へ解決します。

<?php

namespace App\Http\Controllers;

use App\Dtos\UserUpdateDto;
use App\Http\Requests\UserSearchRequest;
use App\Http\Requests\UserUpdateRequest;
use App\Services\UserService;
use App\Support\I18n\I18n;                 // 文字列解決サービス
use App\Support\I18n\I18nKeys;             // キー定数
use App\Exceptions\AppMessageKeyException; // キー例外
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;
use Illuminate\Support\Facades\Log;

class UserController extends Controller
{
    public function __construct(
        private readonly UserService $userService
    ) {}

    public function index(UserSearchRequest $request): View
    {
        $prefix = $request->input('prefix');

        try {
            $users = $this->userService->search($prefix);

            return view('users.index', [
                'prefix' => $prefix,
                'users'  => $users,
            ]);

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] index failed', [
                'key'    => $e->messageKey,
                'prefix' => $prefix,
            ]);

            return view('users.index', [
                'prefix'      => $prefix,
                'users'       => [],
                'globalError' => I18n::t($e->messageKey), // 表示直前に解決
            ]);

        } catch (\Throwable $e) {

            Log::error('[UserController] index unexpected', [
                'prefix' => $prefix,
                'error'  => $e->getMessage(),
            ]);

            return view('users.index', [
                'prefix'      => $prefix,
                'users'       => [],
                'globalError' => I18n::t(I18nKeys::E_UNEXPECTED),
            ]);
        }
    }

    public function edit(int $id): View
    {
        try {
            $dto = $this->userService->getEditDto($id);

            if ($dto === null) {
                abort(404, I18n::t(I18nKeys::E_USER_NOT_FOUND));
            }

            return view('users.edit', [
                'user' => $dto,
            ]);

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] edit failed', [
                'id'  => $id,
                'key' => $e->messageKey,
            ]);

            abort(500, I18n::t($e->messageKey));

        } catch (\Throwable $e) {

            Log::error('[UserController] edit unexpected', [
                'id'    => $id,
                'error' => $e->getMessage(),
            ]);

            abort(500, I18n::t(I18nKeys::E_UNEXPECTED));
        }
    }

    public function update(UserUpdateRequest $request, int $id): RedirectResponse
    {
        $email = $request->input('email');
        $tel   = $request->input('tel');

        try {
            $ok = $this->userService->updateContact(
                new UserUpdateDto(id: $id, email: $email, tel: $tel)
            );

            if (!$ok) {
                return redirect()
                    ->route('users.index')
                    ->with('error', I18n::t(I18nKeys::E_USER_NOT_FOUND));
            }

            return redirect()
                ->route('users.index')
                ->with('success', I18n::t(I18nKeys::S_USER_UPDATED));

        } catch (AppMessageKeyException $e) {

            Log::error('[UserController] update failed', [
                'id'  => $id,
                'key' => $e->messageKey,
            ]);

            return back()
                ->withInput()
                ->with('error', I18n::t($e->messageKey));

        } catch (\Throwable $e) {

            Log::error('[UserController] update unexpected', [
                'id'    => $id,
                'error' => $e->getMessage(),
            ]);

            return back()
                ->withInput()
                ->with('error', I18n::t(I18nKeys::E_UNEXPECTED));
        }
    }
}

14. Blade（画面テンプレート：2画面）

Bladeも「文字列禁止」。固定文言はすべて I18n のキー参照にします。

14-1. 一覧画面（resources/views/users/index.blade.php）

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_INDEX) }}</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body{ font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans JP", sans-serif; margin: 24px; }
    .box{ border: 1px solid #ddd; padding: 16px; border-radius: 8px; margin-bottom: 16px; }
    .ok{ border-left: 6px solid #22c55e; background: #f0fdf4; padding: 12px; border-radius: 8px; }
    .warn{ border-left: 6px solid #f59e0b; background: #fffbeb; padding: 12px; border-radius: 8px; }
    .err{ border-left: 6px solid #ef4444; background: #fef2f2; padding: 12px; border-radius: 8px; }
    table{ width: 100%; border-collapse: collapse; }
    th, td{ border-bottom: 1px solid #eee; padding: 10px; text-align: left; }
    a{ color: #2563eb; text-decoration: none; }
    a:hover{ text-decoration: underline; }
    .muted{ color: #666; font-size: 12px; }
    input{ padding: 8px 10px; width: 240px; }
    button{ padding: 8px 12px; cursor: pointer; }
  </style>
</head>
<body>

  <h1>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_INDEX) }}</h1>

  @if(session('success'))
    <div class="ok">{{ session('success') }}</div>
  @endif

  @if(session('error'))
    <div class="err">{{ session('error') }}</div>
  @endif

  @if(!empty($globalError))
    <div class="err">{{ $globalError }}</div>
  @endif

  <div class="box">
    <form method="GET" action="{{ route('users.index') }}">

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_PREFIX) }}
        <input
          type="text"
          name="prefix"
          value="{{ old('prefix', $prefix) }}"
          placeholder="{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::P_PREFIX) }}"
        >
      </label>

      <button type="submit">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_SEARCH) }}</button>

      <a href="{{ route('users.index') }}" class="muted" style="margin-left:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_CLEAR) }}
      </a>

      @error('prefix')
        {{-- バリデーションが返す $message は「キー」なので、I18nで解決して表示 --}}
        <div class="warn" style="margin-top:10px;">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_PREFIX_RULE) }}
      </div>

    </form>
  </div>

  <div class="box">
    <h2>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_LIST) }}</h2>

    @if(empty($users) || count($users) === 0)
      <div class="warn">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_NO_RESULT) }}</div>
    @else
      <table>
        <thead>
          <tr>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_USERNAME) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_EMAIL) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_TEL) }}</th>
            <th>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::C_ADDRESS) }}</th>
          </tr>
        </thead>
        <tbody>
          @foreach($users as $u)
            <tr>
              <td>
                <a href="{{ route('users.edit', ['id' => $u->id]) }}">{{ $u->username }}</a>
              </td>
              <td>{{ $u->email }}</td>
              <td>{{ $u->tel ?? '' }}</td>
              <td>{{ $u->address ?? '' }}</td>
            </tr>
          @endforeach
        </tbody>
      </table>

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_CLICK_TO_EDIT) }}
      </div>
    @endif
  </div>

</body>
</html>

14-2. 編集画面（resources/views/users/edit.blade.php）

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_EDIT) }}</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <style>
    body{ font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans JP", sans-serif; margin: 24px; }
    .box{ border: 1px solid #ddd; padding: 16px; border-radius: 8px; margin-bottom: 16px; max-width: 640px; }
    .warn{ border-left: 6px solid #f59e0b; background: #fffbeb; padding: 12px; border-radius: 8px; }
    .err{ border-left: 6px solid #ef4444; background: #fef2f2; padding: 12px; border-radius: 8px; }
    label{ display:block; margin-top: 12px; }
    input{ padding: 8px 10px; width: 100%; box-sizing: border-box; }
    button{ padding: 8px 12px; cursor: pointer; margin-top: 14px; }
    .muted{ color: #666; font-size: 12px; }
  </style>
</head>
<body>

  <h1>{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::T_USER_EDIT) }}</h1>

  @if(session('error'))
    <div class="err">{{ session('error') }}</div>
  @endif

  <div class="box">

    <div>
      <div class="muted">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_USERNAME) }}</div>
      <div><b>{{ $user->username }}</b></div>
    </div>

    <div style="margin-top:12px;">
      <div class="muted">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_ADDRESS) }}</div>
      <div>{{ $user->address ?? '' }}</div>
    </div>

    <hr style="margin: 16px 0; border: none; border-top: 1px solid #eee;">

    <form method="POST" action="{{ route('users.update', ['id' => $user->id]) }}">
      @csrf
      @method('PUT')

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_EMAIL) }}
        <input type="text" name="email" value="{{ old('email', $user->email) }}">
      </label>
      @error('email')
        <div class="warn">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <label>
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::L_TEL) }}
        <input type="text" name="tel" value="{{ old('tel', $user->tel) }}">
      </label>
      @error('tel')
        <div class="warn">{{ \App\Support\I18n\I18n::t($message) }}</div>
      @enderror

      <button type="submit">{{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_SAVE) }}</button>

      <a href="{{ route('users.index') }}" style="margin-left:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::A_BACK_TO_LIST) }}
      </a>

      <div class="muted" style="margin-top:10px;">
        {{ \App\Support\I18n\I18n::t(\App\Support\I18n\I18nKeys::N_EDIT_RULE) }}
      </div>

    </form>
  </div>

</body>
</html>

15. 多言語化（「ソース内に文字列を一切ハードコードしない」方式）

15-1. 外部多言語辞書（DBテーブル：i18n_messages）

翻訳文言は DBに保持します（SQLiteでも可）。
アプリは キー と ロケール から文字列を取得し、表示します。
※ DBの中身（翻訳文章）は「運用データ」であり、ソースコードには含めません（要件：文字列ハードコード禁止）。

15-2. Migration（i18n_messages テーブル）

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {

    public function up(): void
    {
        Schema::create('i18n_messages', function (Blueprint $table) {

            $table->id();

            // 例: ja / en / th など
            $table->string('locale', 10);

            // 例: ui.titles.user_index / errors.db_query_failed など
            $table->string('msg_key', 200);

            // 実際の表示文字列（※ソースには置かない：DBデータとして運用）
            $table->text('msg_value');

            // 重複防止
            $table->unique(['locale', 'msg_key']);

            // 参照が多いので索引
            $table->index(['locale', 'msg_key']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('i18n_messages');
    }
};

15-3. Entity（I18nMessage Model）

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class I18nMessage extends Model
{
    protected $table = 'i18n_messages';

    protected $fillable = [
        'locale',
        'msg_key',
        'msg_value',
    ];

    public $timestamps = false;
}

15-4. I18nKeys（キーの定数化：文字列禁止のため）

「キー文字列」すら散らばらないように、キーは定数で一元管理します。
※キーそのものは文言ではないため、ここでは許可（ただし “定数化” して散らばりを防止）。

<?php

namespace App\Support\I18n;

final class I18nKeys
{
    // titles
    public const T_USER_INDEX   = 'ui.titles.user_index';
    public const T_USER_LIST    = 'ui.titles.user_list';
    public const T_USER_EDIT    = 'ui.titles.user_edit';

    // labels
    public const L_PREFIX   = 'ui.labels.prefix';
    public const L_USERNAME = 'ui.labels.username';
    public const L_EMAIL    = 'ui.labels.email';
    public const L_TEL      = 'ui.labels.tel';
    public const L_ADDRESS  = 'ui.labels.address';

    // placeholders
    public const P_PREFIX = 'ui.placeholders.prefix';

    // actions
    public const A_SEARCH       = 'ui.actions.search';
    public const A_CLEAR        = 'ui.actions.clear';
    public const A_SAVE         = 'ui.actions.save';
    public const A_BACK_TO_LIST = 'ui.actions.back_to_list';

    // columns
    public const C_USERNAME = 'ui.columns.username';
    public const C_EMAIL    = 'ui.columns.email';
    public const C_TEL      = 'ui.columns.tel';
    public const C_ADDRESS  = 'ui.columns.address';

    // notes
    public const N_PREFIX_RULE   = 'ui.notes.prefix_rule';
    public const N_NO_RESULT     = 'ui.notes.no_result';
    public const N_CLICK_TO_EDIT = 'ui.notes.click_to_edit';
    public const N_EDIT_RULE     = 'ui.notes.edit_rule';

    // success
    public const S_USER_UPDATED = 'success.user_updated';

    // errors
    public const E_USER_NOT_FOUND    = 'errors.user_not_found';
    public const E_DB_QUERY_FAILED   = 'errors.db_query_failed';
    public const E_DB_UPDATE_FAILED  = 'errors.db_update_failed';
    public const E_UNEXPECTED        = 'errors.unexpected';

    // validation attributes (属性名)
    public const A_PREFIX = 'validation.attributes.prefix';
    public const A_EMAIL  = 'validation.attributes.email';
    public const A_TEL    = 'validation.attributes.tel';

    // validation rules (メッセージ)
    public const V_PREFIX_STRING  = 'validation.rules.prefix.string';
    public const V_PREFIX_MAX     = 'validation.rules.prefix.max';
    public const V_EMAIL_REQUIRED = 'validation.rules.email.required';
    public const V_EMAIL_EMAIL    = 'validation.rules.email.email';
    public const V_EMAIL_MAX      = 'validation.rules.email.max';
    public const V_TEL_MAX        = 'validation.rules.tel.max';
}

15-5. I18nRepository（DBから取得：文字列はDBデータのみ）

<?php

namespace App\Repositories\Contracts;

interface I18nRepositoryInterface
{
    // キーとロケールでメッセージを取得（無ければ null）
    public function findValue(string $locale, string $msgKey): ?string;
}

<?php

namespace App\Repositories\Eloquent;

use App\Models\I18nMessage;
use App\Repositories\Contracts\I18nRepositoryInterface;

class I18nRepository implements I18nRepositoryInterface
{
    public function findValue(string $locale, string $msgKey): ?string
    {
        $row = I18nMessage::query()
            ->select(['msg_value'])
            ->where('locale', $locale)
            ->where('msg_key', $msgKey)
            ->first();

        return $row ? (string)$row->msg_value : null;
    }
}

15-6. I18nService / Helper（キーから文字列を解決）

表示直前に I18n::t(KEY) を呼び、DB辞書から文字列を解決します。
もし辞書に存在しない場合は「キーをそのまま返す」などの運用ポリシーにできます（※ここでは例示のみ。文言は一切埋め込まない）。

<?php

namespace App\Services;

use App\Repositories\Contracts\I18nRepositoryInterface;
use Illuminate\Support\Facades\Cache;

class I18nService
{
    public function __construct(
        private readonly I18nRepositoryInterface $repo
    ) {}

    public function translate(string $locale, string $key): string
    {
        // 高頻度アクセスなのでキャッシュ（キー+ロケール単位）
        $cacheKey = 'i18n:' . $locale . ':' . $key;

        return Cache::remember($cacheKey, 300, function () use ($locale, $key) {

            // DBから取得（文字列はDBデータのみ）
            $val = $this->repo->findValue($locale, $key);

            // 無い場合：キーを返す（文字列を埋め込まないためのフォールバック）
            return $val ?? $key;
        });
    }
}

<?php

namespace App\Support\I18n;

use App\Services\I18nService;

// Blade/Controller から呼びやすい静的ヘルパ
final class I18n
{
    public static function t(string $key): string
    {
        // ロケール決定（例：config/app.php, session, header 等）
        $locale = app(LocaleResolver::class)->resolve();

        return app(I18nService::class)->translate($locale, $key);
    }
}

15-7. LocaleResolver（ロケール決定）

<?php

namespace App\Support\I18n;

use Illuminate\Http\Request;

class LocaleResolver
{
    public function __construct(
        private readonly Request $request
    ) {}

    public function resolve(): string
    {
        // 例：?lang=ja / ?lang=en を優先（業務では session / user設定 / header 等に合わせる）
        $lang = (string)$this->request->query('lang', '');

        // 許可された言語だけに限定（値は config へ寄せることが多い）
        if ($lang === 'ja' || $lang === 'en') {
            return $lang;
        }

        // 既定は ja（※文言ではないのでOK）
        return 'ja';
    }
}

15-8. 「バリデーション文言がキーのまま」になる点の扱い（この仕様での正解）

• FormRequest の messages() で返す値は「文字列」ではなく「キー」にする
• Blade側の @error では $message をそのまま表示せず、I18n::t($message) で解決して表示する
• 属性名（:attribute）を組み立てる場合は、I18n側で置換する拡張を入れる（業務では {attribute} 置換など）

16. 実行手順（SQLiteで起動）

# 1) SQLite DBファイルを作成（空でOK）
touch database/database.sqlite

# 2) .env の DB_DATABASE をプロジェクトの絶対パスに合わせる

# 3) マイグレーション実行
php artisan migrate

# 4) i18n_messages に翻訳データを投入（※運用データとして投入。ソースに埋め込まない）
#    例：CSVインポート、管理画面、別DBから同期、翻訳サービス連携など

# 5) 開発サーバ起動
php artisan serve

# 6) ブラウザでアクセス（例：?lang=ja / ?lang=en）
# http://localhost:8000/users?lang=ja
# http://localhost:8000/users?lang=en

Laravel（PHP）サンプル：注文・請求ルールエンジン（業務ロジック中心）

1. このサンプルで学ぶこと（TypeScript版 → Laravel/PHP版への置き換え）

TypeScript版で扱っていた「文法要素」を、Laravel/PHPでの業務実装の形に置き換えます。
「文法の説明」ではなく、実際の業務ルールを実装する中で、言語機能をどう使うかを理解するのが目的です。

• 型の考え方：PHPの型宣言（int/string/bool/array）と DTO による入力/出力の形固定
• enum（区分値）：PHP 8.1+ の enum を使い、税区分・会員ランク・配送地域を安全に表現
• 配列処理：foreach で注文行を処理（TypeScript の for...of 相当）
• 条件分岐：match（または switch）で税率や送料などの分岐
• 集計：array_reduce で小計などを集計（TypeScript の reduce 相当）
• 定数の扱い：const や private const を使ってルール値を固定し、マジックナンバーを排除
• 入力検証：FormRequest で入力バリデーション（enumの不正値・必須/任意の扱いを明確化）

2. 業務の概要

ユーザーから渡された「注文データ（JSON）」を元に、次を計算します。

• 商品ごとの金額（行小計）と税額
• 顧客ランクやクーポンによる割引
• 配送地域による送料
• 最終的な請求金額（合計）

3. 入力データの考え方（Laravelでの受け取り）

入力は「JSON相当」です。実務では HTTP Request の body（JSON）に相当し、Laravelでは Controller が FormRequest で検証した後に業務ロジックへ渡します。

4. 主な業務ルール（計算仕様）

4-1. 税計算（TaxCategory）

• STANDARD：10%
• REDUCED：8%
• EXEMPT：0%

4-2. 割引（CustomerRank / Coupon）

• GOLD 会員：小計の 5%
• WELCOME10 クーポン：小計の 10%
• 割引は「会員割 + クーポン割」を合算する（本サンプルの前提）

4-3. 送料（Region / FreeShipping）

• TOKYO：500円
• OTHER：800円
• 小計が 10,000円以上で送料無料（送料 = 0）

5. 入力 / 出力データ仕様（コメント付き）

5-1. 入力（注文データ）

業務ロジックに渡される入力データです。実務では HTTP リクエストの body（JSON）に相当します。

// ※ 説明用のためコメント付き（実際の JSON ではコメント不可）
{
  "customerRank": "GOLD",        // 顧客ランク（enum: BRONZE / SILVER / GOLD）
  "region": "TOKYO",             // 配送地域（enum: TOKYO / OTHER）

  "items": [                     // 注文行の配列
    {
      "sku": "A001",              // 商品コード
      "unitPrice": 980,           // 単価（number → PHPではint想定）
      "qty": 2,                   // 数量（number → PHPではint想定）
      "tax": "STANDARD"           // 税区分（enum）
    },
    {
      "sku": "B777",
      "unitPrice": 1500,
      "qty": 1,
      "tax": "REDUCED"
    }
  ],

  "coupon": "WELCOME10"          // クーポンコード（任意・optional）
}

5-2. 出力（計算結果）

業務ロジックが返す計算結果です。APIレスポンスや画面表示用データとしてそのまま使えます。

// 計算結果（出力）
{
  "subtotal": 3460,        // 税抜小計（全行の subtotal 合計）
  "taxTotal": 292,         // 税額合計
  "discount": 346,         // 割引合計（会員 + クーポン）
  "shipping": 500,         // 送料
  "grandTotal": 3906       // 最終請求金額
}

6. Laravelでの実装配置（仕様としての推奨）

本サンプルは「業務ロジック中心」なので、Controller直書きにせず、層を分けます。

app/
  Http/
    Controllers/
      BillingController.php          // HTTP受け口（薄く）
    Requests/
      BillingCalcRequest.php         // 入力バリデーション
  Services/
    BillingRuleEngine.php           // 税/割引/送料/合計の計算本体（業務ロジック）
  Dtos/
    OrderInputDto.php               // 入力DTO（enumに変換済み）
    OrderItemDto.php
    BillingResultDto.php            // 出力DTO
  Enums/
    CustomerRank.php
    Region.php
    TaxCategory.php
    CouponCode.php                  // 任意（WELCOME10など）

Laravel（PHP）実装コード：注文・請求ルールエンジン（APIで計算結果を返す）

0. 前提

• Laravel（9/10/11 いずれでも概ね同様）
• PHP 8.1+（enum を使用）
• このサンプルは DB を使用しません（純粋な計算エンジン）

1. ルーティング（routes/api.php）

計算用APIを 1 本用意します（POSTで注文JSONを受け取り、計算結果JSONを返す）。

<?php
// routes/api.php

use Illuminate\Support\Facades\Route;                 // ルーティング機能
use App\Http\Controllers\BillingController;           // Controller

// 注文・請求の計算（JSON入力 → JSON出力）
Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

2. ファイル構成（業務レベルの分割）

app/
  Enums/
    CustomerRank.php
    Region.php
    TaxCategory.php
    CouponCode.php
  Dtos/
    OrderItemDto.php
    OrderInputDto.php
    BillingResultDto.php
  Services/
    BillingRuleEngine.php
  Http/
    Controllers/
      BillingController.php
    Requests/
      BillingCalcRequest.php

resources/
  lang/
    ja/
      messages.php
      validation.php
    en/
      messages.php
      validation.php

3. enum（業務上の区分値）

3-1. 顧客ランク（app/Enums/CustomerRank.php）

<?php
// app/Enums/CustomerRank.php

namespace App\Enums;

// 顧客ランク（固定の選択肢）
// 文字列を自由入力させるとタイポや想定外値が混ざるため enum にする。
enum CustomerRank: string
{
    case BRONZE = 'BRONZE';  // ブロンズ
    case SILVER = 'SILVER';  // シルバー
    case GOLD   = 'GOLD';    // ゴールド
}

3-2. 配送地域（app/Enums/Region.php）

<?php
// app/Enums/Region.php

namespace App\Enums;

// 配送地域（送料ルールで使用）
enum Region: string
{
    case TOKYO = 'TOKYO';  // 東京
    case OTHER = 'OTHER';  // その他
}

3-3. 税区分（app/Enums/TaxCategory.php）

<?php
// app/Enums/TaxCategory.php

namespace App\Enums;

// 税区分（税率ルールで使用）
enum TaxCategory: string
{
    case STANDARD = 'STANDARD'; // 10%
    case REDUCED  = 'REDUCED';  // 8%
    case EXEMPT   = 'EXEMPT';   // 0%
}

3-4. クーポン（app/Enums/CouponCode.php）

<?php
// app/Enums/CouponCode.php

namespace App\Enums;

// クーポンコード（任意入力だが、許可リストとしてenumにしておくと安全）
enum CouponCode: string
{
    case WELCOME10 = 'WELCOME10'; // 小計の10%割引
}

4. DTO（入力/出力の形を固定する）

Controller から Service へ「配列のまま」渡さず、DTOに詰め替えて渡します。
これにより、業務ロジック層が「入力の形がブレる」事故を防げます。

4-1. 注文明細（app/Dtos/OrderItemDto.php）

<?php
// app/Dtos/OrderItemDto.php

namespace App\Dtos;

use App\Enums\TaxCategory;

// 注文行DTO（1行分）
// 業務ロジックはこのDTOだけを信じて計算する（Request配列を信用しない）。
final class OrderItemDto
{
    public function __construct(
        public readonly string $sku,         // 商品コード
        public readonly int $unitPrice,      // 単価（整数想定）
        public readonly int $qty,            // 数量（整数想定）
        public readonly TaxCategory $tax     // 税区分（enum）
    ) {}
}

4-2. 注文入力（app/Dtos/OrderInputDto.php）

<?php
// app/Dtos/OrderInputDto.php

namespace App\Dtos;

use App\Enums\CustomerRank;
use App\Enums\Region;
use App\Enums\CouponCode;

// 注文入力DTO（全体）
// coupon は任意（null）なので ?CouponCode として持つ。
final class OrderInputDto
{
    /**
     * @param OrderItemDto[] $items 注文明細配列
     */
    public function __construct(
        public readonly CustomerRank $customerRank, // 顧客ランク（enum）
        public readonly Region $region,             // 地域（enum）
        public readonly array $items,               // 明細配列
        public readonly ?CouponCode $coupon         // クーポン（任意）
    ) {}
}

4-3. 計算結果（app/Dtos/BillingResultDto.php）

<?php
// app/Dtos/BillingResultDto.php

namespace App\Dtos;

// 計算結果DTO（出力）
// APIレスポンスや画面表示にそのまま使える形にする。
final class BillingResultDto
{
    public function __construct(
        public readonly int $subtotal,     // 税抜小計
        public readonly int $taxTotal,     // 税額合計
        public readonly int $discount,     // 割引合計
        public readonly int $shipping,     // 送料
        public readonly int $grandTotal    // 最終請求金額
    ) {}

    // JSON返却しやすいように配列化メソッドを用意する（業務でよくやる）
    public function toArray(): array
    {
        return [
            'subtotal'   => $this->subtotal,
            'taxTotal'   => $this->taxTotal,
            'discount'   => $this->discount,
            'shipping'   => $this->shipping,
            'grandTotal' => $this->grandTotal,
        ];
    }
}

5. 業務ロジック本体（Service：app/Services/BillingRuleEngine.php）

税率・割引率・送料などのルールは、定数として 1 か所に集約します（マジックナンバー禁止）。

<?php
// app/Services/BillingRuleEngine.php

namespace App\Services;

use App\Dtos\OrderInputDto;          // 入力DTO
use App\Dtos\BillingResultDto;       // 出力DTO
use App\Enums\CustomerRank;          // 顧客ランクenum
use App\Enums\Region;                // 地域enum
use App\Enums\TaxCategory;           // 税区分enum
use App\Enums\CouponCode;            // クーポンenum

// ルールエンジン（業務ロジック）
// Controller は薄く、計算はすべてここに寄せる。
final class BillingRuleEngine
{
    // 税率（百分率ではなく小数で保持すると計算が分かりやすい）
    private const TAX_STANDARD = 0.10; // 10%
    private const TAX_REDUCED  = 0.08; // 8%
    private const TAX_EXEMPT   = 0.00; // 0%

    // 会員割引率
    private const DISCOUNT_GOLD = 0.05; // 5%

    // クーポン割引率
    private const COUPON_WELCOME10 = 0.10; // 10%

    // 送料
    private const SHIPPING_TOKYO = 500;
    private const SHIPPING_OTHER = 800;

    // 送料無料の閾値（税抜小計で判定）
    private const FREE_SHIPPING_THRESHOLD = 10000;

    // 計算メイン（DTO入力 → DTO出力）
    public function calculate(OrderInputDto $input): BillingResultDto
    {
        // ① 各行の税抜小計を計算しつつ、税額も合計する
        $lineSubtotals = []; // 行小計を集める配列（後でreduceで合計する例）
        $taxTotal = 0;       // 税額合計

        // 注文明細を順に処理する（TypeScriptの for...of 相当）
        foreach ($input->items as $item) {

            // 行小計（税抜）：単価×数量
            $subtotal = $item->unitPrice * $item->qty;

            // 行小計を配列に積む（集計用）
            $lineSubtotals[] = $subtotal;

            // 税率を税区分から決定する（matchで安全に分岐）
            $rate = match ($item->tax) {
                TaxCategory::STANDARD => self::TAX_STANDARD,
                TaxCategory::REDUCED  => self::TAX_REDUCED,
                TaxCategory::EXEMPT   => self::TAX_EXEMPT,
            };

            // 税額（端数処理は要件次第。ここでは四捨五入ではなく「切り捨て」にする例）
            // ※実務では「端数処理ポリシー」を仕様で固定すること。
            $lineTax = (int) floor($subtotal * $rate);

            // 税額合計に加算する
            $taxTotal += $lineTax;
        }

        // ② 小計合計（reduceで集計する例：TypeScript reduce の置き換え）
        $subtotalTotal = array_reduce(
            $lineSubtotals,
            function (int $carry, int $value): int {
                // carry は今までの合計、value は現在の要素
                return $carry + $value;
            },
            0 // 初期値（合計0）
        );

        // ③ 割引計算（会員 + クーポン）
        $memberDiscount = $this->calcMemberDiscount($input->customerRank, $subtotalTotal);
        $couponDiscount = $this->calcCouponDiscount($input->coupon, $subtotalTotal);

        // 割引合計（要件：会員割＋クーポン割を合算）
        $discountTotal = $memberDiscount + $couponDiscount;

        // ④ 送料計算（地域 + 送料無料条件）
        $shipping = $this->calcShipping($input->region, $subtotalTotal);

        // ⑤ 最終請求金額
        $grandTotal = $subtotalTotal + $taxTotal - $discountTotal + $shipping;

        // DTOで返す（ControllerはこのDTOを配列化してJSONにするだけ）
        return new BillingResultDto(
            subtotal: $subtotalTotal,
            taxTotal: $taxTotal,
            discount: $discountTotal,
            shipping: $shipping,
            grandTotal: $grandTotal
        );
    }

    // 会員割引の計算（ルールを関数に分離して読みやすくする）
    private function calcMemberDiscount(CustomerRank $rank, int $subtotal): int
    {
        // GOLD以外は割引なし
        if ($rank !== CustomerRank::GOLD) {
            return 0;
        }

        // GOLD：小計の5%
        return (int) floor($subtotal * self::DISCOUNT_GOLD);
    }

    // クーポン割引の計算（couponは任意なので null を考慮）
    private function calcCouponDiscount(?CouponCode $coupon, int $subtotal): int
    {
        // クーポンが無ければ割引なし
        if ($coupon === null) {
            return 0;
        }

        // クーポン別に分岐（今後増える前提でmatchにする）
        $rate = match ($coupon) {
            CouponCode::WELCOME10 => self::COUPON_WELCOME10,
        };

        // 小計に割引率を掛ける
        return (int) floor($subtotal * $rate);
    }

    // 送料計算（送料無料条件もここで吸収）
    private function calcShipping(Region $region, int $subtotal): int
    {
        // 送料無料条件：小計が閾値以上
        if ($subtotal >= self::FREE_SHIPPING_THRESHOLD) {
            return 0;
        }

        // 地域ごとの基本送料
        return match ($region) {
            Region::TOKYO => self::SHIPPING_TOKYO,
            Region::OTHER => self::SHIPPING_OTHER,
        };
    }
}

6. 入力バリデーション（FormRequest：app/Http/Requests/BillingCalcRequest.php）

入力の形（必須/任意）と、enumとして許可される値をここで確定させます。
これにより Service は「正しい入力だけ来る」前提で書けます（業務コードの王道）。

<?php
// app/Http/Requests/BillingCalcRequest.php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;           // FormRequest
use Illuminate\Validation\Rule;                       // ルール定義
use App\Enums\CustomerRank;                           // enum
use App\Enums\Region;                                 // enum
use App\Enums\TaxCategory;                            // enum
use App\Enums\CouponCode;                             // enum

final class BillingCalcRequest extends FormRequest
{
    // 認可（このサンプルは誰でもOK）
    public function authorize(): bool
    {
        return true;
    }

    // バリデーションルール
    public function rules(): array
    {
        return [
            // 顧客ランク（必須、enumのいずれか）
            'customerRank' => ['required', Rule::enum(CustomerRank::class)],

            // 配送地域（必須、enumのいずれか）
            'region' => ['required', Rule::enum(Region::class)],

            // 注文明細（必須、配列、最低1行）
            'items' => ['required', 'array', 'min:1'],

            // items[*].sku（必須、文字列、最大長）
            'items.*.sku' => ['required', 'string', 'max:50'],

            // items[*].unitPrice（必須、整数、0以上）
            'items.*.unitPrice' => ['required', 'integer', 'min:0'],

            // items[*].qty（必須、整数、1以上）
            'items.*.qty' => ['required', 'integer', 'min:1'],

            // items[*].tax（必須、enumのいずれか）
            'items.*.tax' => ['required', Rule::enum(TaxCategory::class)],

            // coupon（任意、指定される場合はenumのいずれか）
            'coupon' => ['nullable', Rule::enum(CouponCode::class)],
        ];
    }

    // 属性名（:attribute）を多言語化で出したい場合は lang/validation.php の attributes を使う
    // ここでは上書きしない（業務では共通化が多い）
}

7. Controller（HTTPは薄く：app/Http/Controllers/BillingController.php）

Controller は「入力をDTO/enumに変換 → Service呼び出し → JSON返却」だけにします。
エラー時メッセージはlangから取得し、ソースに直書きしません。

<?php
// app/Http/Controllers/BillingController.php

namespace App\Http\Controllers;

use App\Http\Requests\BillingCalcRequest;     // バリデーション済み入力
use App\Services\BillingRuleEngine;           // 業務ロジック
use App\Dtos\OrderInputDto;                   // 入力DTO
use App\Dtos\OrderItemDto;                    // 入力DTO（明細）
use App\Enums\CustomerRank;                   // enum変換
use App\Enums\Region;                         // enum変換
use App\Enums\TaxCategory;                    // enum変換
use App\Enums\CouponCode;                     // enum変換
use Illuminate\Http\JsonResponse;             // JSONレスポンス型
use Illuminate\Support\Facades\Log;           // ログ

final class BillingController extends Controller
{
    // ServiceをDI（テスト容易性のため）
    public function __construct(
        private readonly BillingRuleEngine $engine
    ) {}

    // 計算API
    public function calc(BillingCalcRequest $request): JsonResponse
    {
        // ここに来た時点で入力はバリデーション済み
        // ※ enum 不正値は 422（Validation error）になる

        try {
            // 入力配列を取り出す（バリデーション済み）
            $data = $request->validated();

            // customerRank を enum に変換（Rule::enumで保証されるが、DTOとして明示）
            $rank = CustomerRank::from($data['customerRank']);

            // region を enum に変換
            $region = Region::from($data['region']);

            // coupon は任意（nullの可能性）
            $coupon = isset($data['coupon']) && $data['coupon'] !== null
                ? CouponCode::from($data['coupon'])
                : null;

            // items を DTO 配列へ変換
            $items = [];

            foreach ($data['items'] as $row) {

                // tax を enum に変換
                $tax = TaxCategory::from($row['tax']);

                // 明細DTOを作る（業務ロジックはDTOのみを信用する）
                $items[] = new OrderItemDto(
                    sku: (string) $row['sku'],
                    unitPrice: (int) $row['unitPrice'],
                    qty: (int) $row['qty'],
                    tax: $tax
                );
            }

            // 入力DTOを作る
            $inputDto = new OrderInputDto(
                customerRank: $rank,
                region: $region,
                items: $items,
                coupon: $coupon
            );

            // 業務ロジック実行
            $resultDto = $this->engine->calculate($inputDto);

            // 正常レスポンス（メッセージは不要。必要なら lang から返す）
            return response()->json($resultDto->toArray(), 200);

        } catch (\Throwable $e) {

            // 原因調査用ログ（ユーザーには詳細を出さない）
            Log::error('[BillingController] calc failed', [
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString(),
            ]);

            // ユーザー向けの汎用エラー文言（langから取得）
            return response()->json([
                'message' => __('messages.errors.unexpected'),
            ], 500);
        }
    }
}

8. 多言語化（resources/lang）

「ユーザーへ返す文言」はソースに直書きせず、__('...') で lang から取得します。
※langファイルは「文字列を置く場所」なので、そこに文字列があるのは正常です（ハードコード先がlangというだけ）。

8-1. messages.php（ja：resources/lang/ja/messages.php）

<?php
// resources/lang/ja/messages.php

return [
    'errors' => [
        // 想定外エラー（500時に返す）
        'unexpected' => '予期しないエラーが発生しました。',
    ],
];

8-2. messages.php（en：resources/lang/en/messages.php）

<?php
// resources/lang/en/messages.php

return [
    'errors' => [
        // Unexpected error (returned on HTTP 500)
        'unexpected' => 'An unexpected error occurred.',
    ],
];

8-3. validation.php（ja：resources/lang/ja/validation.php）

バリデーションメッセージ/属性名もlangで管理します（Laravel標準の仕組み）。

<?php
// resources/lang/ja/validation.php

return [
    'required' => ':attribute は必須です。',
    'array'    => ':attribute の形式が不正です。',
    'min'      => ':attribute は :min 以上で指定してください。',
    'integer'  => ':attribute は整数で指定してください。',
    'string'   => ':attribute は文字列で指定してください。',
    'max'      => ':attribute は :max 文字以内で指定してください。',
    'enum'     => ':attribute の値が不正です。',

    // :attribute に入る表示名（業務ではここを整備するのが大事）
    'attributes' => [
        'customerRank'    => '顧客ランク',
        'region'          => '配送地域',
        'items'           => '注文明細',
        'items.*.sku'     => '商品コード',
        'items.*.unitPrice' => '単価',
        'items.*.qty'     => '数量',
        'items.*.tax'     => '税区分',
        'coupon'          => 'クーポン',
    ],
];

9. 動作確認（curl例）

curl -X POST http://localhost:8000/api/billing/calc \
  -H "Content-Type: application/json" \
  -d '{
    "customerRank":"GOLD",
    "region":"TOKYO",
    "items":[
      {"sku":"A001","unitPrice":980,"qty":2,"tax":"STANDARD"},
      {"sku":"B777","unitPrice":1500,"qty":1,"tax":"REDUCED"}
    ],
    "coupon":"WELCOME10"
  }'

{
  "subtotal": 3460,
  "taxTotal": 292,
  "discount": 519,
  "shipping": 500,
  "grandTotal": 3733
}

10. 仕様チェック（要件の満たし方）

• items は foreach で行計算（for...of相当）
• 区分値は PHP enum（税区分/会員ランク/地域/クーポン）
• 税率・割引率・送料・送料無料閾値は定数化（マジックナンバー排除）
• 集計は array_reduce 例を提示（reduce相当）
• ユーザー向けメッセージは __('...') で lang から取得（ソース直書きなし）
• 入力不正は FormRequest + lang/validation で 422 を返す（業務的に安全）

Laravel ルーティング文法の詳細：Route::post(...)->name(...) を読み解く

1. 対象コード

<?php
// routes/api.php

use Illuminate\Support\Facades\Route;       // ルーティング定義に使う Facade
use App\Http\Controllers\BillingController; // 呼び出したい Controller クラス

Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

2. まず結論：あなたの理解で合っています

3. Route::post() の文法を分解

3-1. Route とは何か

Illuminate\Support\Facades\Route は Facade（ファサード） です。
ルーティング機能（Route登録）を簡単な書き方で呼び出せるようにした入口です。

3-2. ::post は「POSTメソッド専用のルート登録」

Route::post(...) は、HTTPメソッドが POST のときだけ一致するルートを登録します。
つまり、同じパスでも GET で叩いた場合はこのルートには一致しません（405等になります）。

3-3. 第1引数 '/billing/calc' は「URLパス（URI）」

ここで指定しているのはドメインを除いた「パス部分」です。

• /billing/calc は「相対パス」であり、ホスト名は含みません
• routes/api.php に書くルートは通常 /api が自動で付くため、実際のパスは /api/billing/calc になります

3-4. 第2引数 [BillingController::class, 'calc'] は「呼び出す処理（アクション）」

第2引数は「このルートに一致したとき、何を実行するか」を表します。
Laravelでは以下の書き方が一般的です。

（A）Controllerを呼ぶ書き方：[クラス, 'メソッド名']

[BillingController::class, 'calc']

• BillingController::class はクラス名（完全修飾される）を文字列として返します
  • 実体は 'App\Http\Controllers\BillingController' のような文字列です
• 'calc' は呼び出すメソッド名（文字列）です

したがって、あなたの質問に対する答えはこうです：

（B）無名関数（クロージャ）で書くこともできる

Route::post('/billing/calc', function () {
    return ['ok' => true];
});

ただし業務コードでは Controller に寄せるのが一般的です（責務分離・テスト容易性のため）。

4. ->name('billing.calc') の意味（ルート名）

4-1. ルート名とは

->name('billing.calc') は、このルートに 「名前（ルート名）」を付けています。
ルート名を付けると、URLの文字列をベタ書きせずに「名前」からURLを生成できるようになります。

4-2. ルート名を使うメリット（業務で重要）

• URLが変わっても、ルート名が同じなら呼び出し側の修正が最小になる
• BladeやControllerで URL を直接書かずに済む（保守性が上がる）
• ルート一覧を見たときに「何のルートか」が分かりやすい

4-3. ルート名の使い方（例）

（A）URLを生成する（routeヘルパ）

// ルート名からURLを生成
$url = route('billing.calc');

（B）リダイレクトする（redirect）

// ルート名へリダイレクト（GET向き）
return redirect()->route('billing.calc');

（C）Bladeでフォームのactionに使う

<form method="POST" action="{{ route('billing.calc') }}">
  @csrf
  ...
</form>

5. ルーティングの書き方：よく使うパターン一覧

5-1. HTTPメソッド別

Route::get('/path', ...);     // GET
Route::post('/path', ...);    // POST
Route::put('/path', ...);     // PUT（更新）
Route::patch('/path', ...);   // PATCH（部分更新）
Route::delete('/path', ...);  // DELETE

5-2. ルートパラメータ（URLに変数を含める）

// /users/10 の「10」を {id} として受け取る
Route::get('/users/{id}', [UserController::class, 'show'])
    ->whereNumber('id')        // idは数値のみ
    ->name('users.show');

5-3. ミドルウェア（認証など）

Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->middleware('auth')       // 認証が必要
    ->name('billing.calc');

5-4. ルートグループ（prefix / middleware / namespace）

Route::prefix('billing')->group(function () {
    Route::post('/calc', [BillingController::class, 'calc'])
        ->name('billing.calc');
});

6. まとめ（この1行がやっていること）

• Route::post(...)：POSTのときだけ一致するルートを登録する
• '/billing/calc'：URI（パス）を指定する（api.phpなら通常 /api が前につく）
• [BillingController::class, 'calc']：一致したら Controller の calc() を実行する
• ->name('billing.calc')：このルートに名前を付け、route('billing.calc') でURL生成できるようにする

なぜ routes/api.php のルートには /api が付くのか（コードで理解する）

1. あなたが書いているコード（api.php 側）

まず、あなたが実際に書いているコードを確認します。

<?php
// routes/api.php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\BillingController;

// 注文・請求の計算（JSON入力 → JSON出力）
Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

この時点では、あなたは /billing/calc としか書いていません。
にもかかわらず、実際のURLは /api/billing/calc になります。

2. 「/api」を付けている正体のコード（Laravel側）

2-1. Laravel 10 までの典型例：RouteServiceProvider

Laravel 10 以前（またはそれに近い構成）では、次のファイルがルート読み込みの中心です。

<?php
// app/Providers/RouteServiceProvider.php

namespace App\Providers;

use Illuminate\Support\Facades\Route;
use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;

class RouteServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->routes(function () {

            // 👇 ここが重要
            Route::prefix('api')
                ->middleware('api')
                ->group(base_path('routes/api.php'));

            Route::middleware('web')
                ->group(base_path('routes/web.php'));
        });
    }
}

つまり、Laravelは内部的に次のようなことをしているのと同じです。

// Laravelが内部でやっているイメージ

Route::prefix('api')->group(function () {

    // ↓ あなたが api.php に書いたコードが、ここに「展開」される
    Route::post('/billing/calc', [BillingController::class, 'calc'])
        ->name('billing.calc');

});

その結果、実際に登録されるURLは次のようになります。

POST /api/billing/calc

3. Laravel 11 の場合（bootstrap/app.php）

Laravel 11 では RouteServiceProvider が廃止され、 ルート定義は bootstrap/app.php に集約されています。

<?php
// bootstrap/app.php（一部抜粋）

use Illuminate\Support\Facades\Route;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        api: __DIR__.'/../routes/api.php',
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
    )
    ->create();

この withRouting() の内部実装で、Laravelは 「api ルートには api プレフィックスを付ける」 という処理を行っています。

4. もし自分で書くとしたら（完全に同じ意味のコード）

あなたが「/api を付ける理由」を完全に理解するために、 同じことを自分で書くとどうなるかを示します。

// routes/web.php に書いたと仮定

Route::prefix('api')->group(function () {

    Route::post('/billing/calc', [BillingController::class, 'calc'])
        ->name('billing.calc');

});

これは routes/api.php に書いた場合と まったく同じURL になります。

5. まとめ（重要ポイントだけ）

• /api が付くのは Laravelのルート読み込み設定によるもの
• api.php というファイル名自体に魔法があるわけではない
• 内部的には Route::prefix('api')->group(...) と同じ
• そのため Route::post('/billing/calc', ...) → /api/billing/calc になる

->name('billing.calc') とは何か（ルート名の本当の意味）

1. ルート名がない場合の問題点

まず、->name() を付けない場合を考えます。

// ルート名なし
Route::post('/billing/calc', [BillingController::class, 'calc']);

この場合、URL を使う側（Controller / Blade / JS）は URL文字列を直接書くしかありません。

// URLを直書き（変更に弱い）
$url = '/api/billing/calc';

2. ->name() を付けた場合に何が変わるのか

Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

この1行で、Laravelの内部には次のような「対応表」が登録されます。

ルート名: billing.calc
↓
HTTPメソッド: POST
URI: /api/billing/calc
処理: BillingController@calc

3. ルート名を使うと何ができるのか

3-1. URLを「生成」できる（routeヘルパ）

// ルート名からURLを生成
$url = route('billing.calc');

// 実際に生成される値
// https://example.com/api/billing/calc

3-2. Bladeテンプレートで使える

<form method="POST" action="{{ route('billing.calc') }}">
  @csrf
  ...
</form>

3-3. リダイレクトで使える

// 処理後に同じルートへ戻したい場合
return redirect()->route('billing.calc');

4. ルート名があるからできる「安全な変更」

例えば、仕様変更で URL を次のように変えたとします。

// 変更前
Route::post('/billing/calc', ...)->name('billing.calc');

// 変更後（URLだけ変更）
Route::post('/billing/calculate', ...)->name('billing.calc');

5. ルート名の命名規則（業務での慣習）

6. まとめ（この1行の本質）

• ->name('billing.calc') は URL の別名ではない
• 「このルートを指すための安定した識別子」を付けている
• route('billing.calc') により、Laravelが正しいURLを計算する
• URL変更に強い業務コードを書くための必須機能

Route::name() は何が得なのか（URL比較→何が起きるかまで）

1. まず最初に：name を付けても「URLは変わりません」

ここが最重要ポイントです。
name を付けても付けなくても、ユーザーが叩くURLは同じです。
変わるのは「アプリの中でそのURLをどう扱うか」です。

2. 「何が得するのか？」を、起きる事態で説明します

2-1. 事態①：URLが仕様変更される（業務で頻発）

例：API設計変更で、URLをこう変えることになったとします。

❌ name なしで起きること（面倒な事態）

$url = '/api/billing/calc'; // ← ここを変更しないと壊れる
Http::post($url, $payload);

<form method="POST" action="/api/billing/calc">...</form>

fetch('/api/billing/calc', { method: 'POST', ... });

✅ name ありで起きること（得する事態）

// 変更前
Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

// 変更後（URLだけ変更、nameは同じ）
Route::post('/billing/calculate', [BillingController::class, 'calc'])
    ->name('billing.calc');

$url = route('billing.calc'); // ← 常に「最新のURL」に解決される
Http::post($url, $payload);

2-2. 事態②：環境によってURLの先頭が変わる（ローカル/本番/サブディレクトリ）

例えば次のような環境差が現実に起きます。

2-3. 事態③：パラメータ付きURLで特に差が出る

id のようなパラメータがあると、直書きはさらに事故りやすいです。

// 例：ユーザー詳細
Route::get('/users/{id}', [UserController::class, 'show'])
    ->name('users.show');

// 正しいURLを自動生成：/api/users/10 のようになる
$url = route('users.show', ['id' => 10]);

3. まとめ：name を付けた場合に「得すること」

• URLが変更されても、修正は「ルート定義1か所」で済む
• 環境差（localhost / 本番 / サブディレクトリ）をLaravelが吸収してくれる
• パラメータ付きURLの組み立てミスを減らせる
• 結果として「直書きURLが散らばる事故（修正漏れ・環境不具合）」を防げる

「使う側の関数内で何が変わるのか」：name なし vs name あり（全体像）

0. 前提：このAPIの「実際のURL」はこうなる

1. ケースA：->name() なし（使う側がURL文字列を持つ）

1-1. ルート定義（nameなし）

// routes/api.php
Route::post('/billing/calc', [BillingController::class, 'calc']);

1-2. 使う側の関数（例：Blade画面からAPIを叩くController）

例として「注文入力画面を表示するController」が、APIのエンドポイントURLをビューへ渡す場面を想定します。

<?php
// app/Http/Controllers/OrderPageController.php

namespace App\Http\Controllers;

use Illuminate\View\View;

class OrderPageController extends Controller
{
    public function show(): View
    {
        // ❌ name がないので、URLを直書きするしかない
        $billingCalcUrl = '/api/billing/calc';

        return view('order.page', [
            'billingCalcUrl' => $billingCalcUrl,
        ]);
    }
}

1-3. Blade（JSがURLを受け取ってfetchする）

<!-- resources/views/order/page.blade.php -->

<script>
  // Controllerから渡されたURL（直書き由来）
  const billingCalcUrl = @json($billingCalcUrl);

  async function calcBilling(payload){
    const res = await fetch(billingCalcUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    return await res.json();
  }
</script>

1-4. そして「URL変更」が起きると何が起きるか

2. ケースB：->name('billing.calc') あり（使う側は「名前」だけを持つ）

2-1. ルート定義（nameあり）

// routes/api.php
Route::post('/billing/calc', [BillingController::class, 'calc'])
    ->name('billing.calc');

2-2. 使う側の関数（同じ OrderPageController でもこう変わる）

<?php
// app/Http/Controllers/OrderPageController.php

namespace App\Http\Controllers;

use Illuminate\View\View;

class OrderPageController extends Controller
{
    public function show(): View
    {
        // ✅ URLを直書きしない。ルート名からLaravelに生成させる。
        //    （環境によって http://localhost:8000/api/... なども正しく解決される）
        $billingCalcUrl = route('billing.calc');

        return view('order.page', [
            'billingCalcUrl' => $billingCalcUrl,
        ]);
    }
}

2-3. Blade（JS側は同じでもOK）

Blade/JSは「URL文字列」をもらって使うだけなので、ここは変わらないことが多いです。
変わるのはURL文字列の作り方（生成方法）です。

<!-- resources/views/order/page.blade.php -->

<script>
  // Controllerが route('billing.calc') で生成したURLが入る
  const billingCalcUrl = @json($billingCalcUrl);

  async function calcBilling(payload){
    const res = await fetch(billingCalcUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
    return await res.json();
  }
</script>

2-4. そして「URL変更」が起きると何が起きるか

// routes/api.php（ここだけ変更する）
Route::post('/billing/calculate', [BillingController::class, 'calc'])
    ->name('billing.calc'); // ← nameは同じにしておく

3. まとめ：あなたが知りたかった「使う側の関数内の違い」

Laravelで「extends が必要/推奨」なクラス一覧（定義例つき）

1. extends が必要（またはほぼ必須）なもの

2. extends が不要（プレーンPHPクラスでOK）なもの

3. 「関数の定義部分」つき：最小のクラス定義例

3-1. Controller（extends が必要）

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller; // 基底Controller
use Illuminate\Http\JsonResponse;    // JSONレスポンス型
use Illuminate\Http\Request;         // リクエスト

class BillingController extends Controller
{
    // POST /api/billing/calc を処理するアクション
    public function calc(Request $request): JsonResponse
    {
        // ...処理...
        return response()->json(['ok' => true]);
    }
}

3-2. FormRequest（extends が必要）

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class BillingCalcRequest extends FormRequest
{
    // 認可（ログイン必須などをここで判定できる）
    public function authorize(): bool
    {
        return true;
    }

    // バリデーションルール
    public function rules(): array
    {
        return [
            'region' => ['required', 'string'],
            'items'  => ['required', 'array'],
        ];
    }
}

3-3. Eloquent Model（Entity相当：extends が必要）

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';

    // 必要なら上書き（例：Laravel標準のupdated_atを使わない等）
    public $timestamps = false;
}

3-4. Migration（extends が必要）

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {

    // テーブル作成
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('username');
            $table->string('email');
            $table->string('tel')->nullable();
            $table->string('address')->nullable();
            $table->timestamp('update_at')->nullable();
        });
    }

    // ロールバック
    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

3-5. ServiceProvider（extends が必要）

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\Contracts\UserRepositoryInterface;
use App\Repositories\Eloquent\UserRepository;

class AppServiceProvider extends ServiceProvider
{
    // DI登録（起動時に呼ばれる）
    public function register(): void
    {
        $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
    }

    // 起動後処理（必要なら）
    public function boot(): void
    {
        //
    }
}

3-6. Seeder（extends が必要）

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class UsersSeeder extends Seeder
{
    // db:seed で呼ばれる
    public function run(): void
    {
        DB::table('users')->insert([
            'username' => 'alice',
            'email'    => 'alice@example.com',
            'tel'      => '090-0000-0000',
            'address'  => 'Tokyo',
            'update_at' => now(),
        ]);
    }
}

3-7. Exception（extends が必要：Throwableにするため）

<?php

namespace App\Exceptions;

use RuntimeException;

class ServiceException extends RuntimeException
{
}

3-8. Service（extends 不要：プレーンPHP）

<?php

namespace App\Services;

class BillingService
{
    // 業務ロジック（計算処理）
    public function calc(array $input): array
    {
        // ...計算...
        return ['grandTotal' => 0];
    }
}

3-9. Repository（extends 不要：プレーンPHP）

<?php

namespace App\Repositories\Eloquent;

use App\Repositories\Contracts\UserRepositoryInterface;

class UserRepository implements UserRepositoryInterface
{
    public function findById(int $id): ?array
    {
        // ...DBアクセス...
        return null;
    }
}

3-10. DTO（extends 不要：プレーンPHP）

<?php

namespace App\Dtos;

class UserUpdateDto
{
    public function __construct(
        public int $id,
        public string $email,
        public ?string $tel
    ) {}
}

4. ひとこと（業務の勘所）

Laravel の主要クラス種類を「いつ・なぜ使うか」で理解する

Laravel には多くの「クラスの種類」がありますが、
初心者が一番つまずくのは 「結局、どの局面でどれを使えばいいのか分からない」点です。
ここでは 実際の業務の流れに沿って、
「この局面ではこのクラス」という形で説明します。

全体像（まずこれだけ覚えてください）

1. Controller（必須・最初に通る）

役割： ブラウザやAPIからのリクエストを最初に受け取る場所。
「受付係」です。

<?php
class UserController extends Controller
{
    // GET /users
    public function index()
    {
        return view('users.index');
    }
}

2. FormRequest（入力チェック専用）

役割： フォームやAPI入力が正しいかを検証する。
Controller に if 文を大量に書かないための仕組み。

<?php
class UserStoreRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'email' => ['required', 'email'],
        ];
    }
}

3. Eloquent Model（Entity相当）

役割： DBテーブルの1行を PHP オブジェクトとして扱う。

<?php
class User extends Model
{
    protected $table = 'users';
}

4. Migration（DB設計そのもの）

役割： テーブル構造をコードで管理する。

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('email');
});

5. Seeder（初期データ）

役割： テストや初期状態用のデータ投入。

DB::table('users')->insert([
    'email' => 'test@example.com',
]);

6. Factory（ダミーデータ生成）

役割： テスト用データを大量生成。

User::factory()->count(10)->create();

7. ServiceProvider（アプリ起動時の設定）

役割： アプリ起動時に一度だけ行う設定。

public function register()
{
    $this->app->bind(
        UserRepositoryInterface::class,
        UserRepository::class
    );
}

8. Console Command（CLI処理）

役割： バッチ処理・管理用コマンド。

class CleanupCommand extends Command
{
    protected $signature = 'cleanup:users';

    public function handle()
    {
        // バッチ処理
    }
}

9. Job（時間がかかる処理）

役割： メール送信などを裏で実行。

class SendMailJob implements ShouldQueue
{
    public function handle()
    {
        // 重い処理
    }
}

10. Event / Listener（何か起きたら反応）

役割： 「〇〇が起きたら××する」を分離。

// Event
class UserRegistered {}

// Listener
class SendWelcomeMail
{
    public function handle(UserRegistered $event)
    {
        // 登録後メール
    }
}

最後に（初心者向けの覚え方）

• 画面/API → Controller
• 入力チェック → FormRequest
• DB → Model
• DB設計 → Migration
• 初期データ → Seeder / Factory
• 重い処理 → Job
• 連動処理 → Event / Listener

SQLite3（Laravel）で「テーブル作成 → 初期データ投入」までの流れ（Mermaid + コード例）

1) 全体の流れ（Mermaid）

1-1. 実行の流れ（テスト/ローカルでよくあるパターン）

1-2. 「どのクラス（関数）が動くか」の対応表

2) SQLite 設定（.env と DBファイル）

2-1. .env（SQLiteを使う）

DB_CONNECTION=sqlite
DB_DATABASE=/absolute/path/to/your-project/database/database.sqlite

2-2. SQLiteファイルを作る（無いと接続エラー）

# プロジェクト直下で
touch database/database.sqlite

3) テーブル定義（Migrationコード例）

3-1. users テーブル

カラム： id, userName, tel, email, address, update_at

<?php
// database/migrations/2026_02_16_000001_create_users_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {

    // テーブル作成（migrate で呼ばれる）
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {

            $table->id();                         // id（主キー・auto increment）
            $table->string('userName', 100);      // userName（ユーザー名）
            $table->string('tel', 50)->nullable();// tel（電話、null可）
            $table->string('email', 255);         // email
            $table->string('address', 255)->nullable(); // address（住所、null可）

            // 要件：update_at（通常の updated_at ではない）
            $table->timestamp('update_at')->nullable();

            // 検索されがちな項目は index を張る（任意）
            $table->index('userName');
            $table->index('email');
        });
    }

    // ロールバック（migrate:rollback で呼ばれる）
    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

3-2. 在庫テーブル（ここでは inventories と命名）

カラム： id, 商品コード, 在庫量, 次回入庫日, 入荷単位個数, 入荷値段, 販売価格, update_at

<?php
// database/migrations/2026_02_16_000002_create_inventories_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {

    public function up(): void
    {
        Schema::create('inventories', function (Blueprint $table) {

            $table->id();                                  // id
            $table->string('product_code', 50);            // 商品コード
            $table->integer('stock_qty');                  // 在庫量（整数）
            $table->date('next_arrival_date')->nullable(); // 次回入庫日（null可）
            $table->integer('arrival_unit_qty');           // 入荷単位個数（例：12個単位）
            $table->integer('arrival_price');              // 入荷値段（仕入れ価格・整数）
            $table->integer('sale_price');                 // 販売価格（整数）
            $table->timestamp('update_at')->nullable();     // 更新日時（独自）

            $table->unique('product_code');                // 商品コードはユニーク想定
            $table->index('next_arrival_date');            // 任意（検索用）
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('inventories');
    }
};

4) 初期データ投入（Seederコード例）

4-1. DatabaseSeeder（Seederの入口）

<?php
// database/seeders/DatabaseSeeder.php

namespace Database\Seeders;

use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    // db:seed / --seed で最初に呼ばれる
    public function run(): void
    {
        // 個別Seederを呼ぶ（必要な分だけ）
        $this->call([
            UsersSeeder::class,
            InventoriesSeeder::class,
        ]);
    }
}

4-2. users 初期データ

<?php
// database/seeders/UsersSeeder.php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class UsersSeeder extends Seeder
{
    // 初期データ投入（INSERT）
    public function run(): void
    {
        DB::table('users')->insert([
            [
                'userName'  => 'alice',
                'tel'       => '090-1111-1111',
                'email'     => 'alice@example.com',
                'address'   => 'Tokyo',
                'update_at' => now(),
            ],
            [
                'userName'  => 'bob',
                'tel'       => null,
                'email'     => 'bob@example.com',
                'address'   => 'Osaka',
                'update_at' => now(),
            ],
        ]);
    }
}

4-3. inventories 初期データ

<?php
// database/seeders/InventoriesSeeder.php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;

class InventoriesSeeder extends Seeder
{
    public function run(): void
    {
        DB::table('inventories')->insert([
            [
                'product_code'      => 'A001',
                'stock_qty'         => 25,
                'next_arrival_date' => '2026-03-01',
                'arrival_unit_qty'  => 10,
                'arrival_price'     => 800,
                'sale_price'        => 1200,
                'update_at'         => now(),
            ],
            [
                'product_code'      => 'B777',
                'stock_qty'         => 0,
                'next_arrival_date' => '2026-02-20',
                'arrival_unit_qty'  => 12,
                'arrival_price'     => 1500,
                'sale_price'        => 2200,
                'update_at'         => now(),
            ],
        ]);
    }
}

5) 実行コマンド（「作成→投入」を一発で）

5-1. ローカル/テストで定番：作り直して seed まで

# DBを作り直して（全テーブルDROP→作成）seedまで実行
php artisan migrate:fresh --seed

6) 「PHP起動時（テスト開始時）に自動でやる」例：PHPUnit setUp（テスト環境）

テストでは「テスト開始時にDBを必ず新しくして初期データを入れる」ことが多いです。
その場合、テストクラスの setUp で artisan を呼ぶことがあります（例）。

<?php
// tests/Feature/BootstrapDbTest.php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Support\Facades\Artisan;

class BootstrapDbTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();

        // ① テーブル作り直し（fresh）
        // ② 初期データ投入（--seed）
        Artisan::call('migrate:fresh', ['--seed' => true]);
    }

    public function test_example(): void
    {
        $this->assertTrue(true);
    }
}

7) 参考：Model（Entity相当）を置く場合（update_atなのでtimestamps無効化）

7-1. User モデル

<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';

    // Laravel標準の created_at / updated_at を使わない
    public $timestamps = false;

    protected $fillable = [
        'userName', 'tel', 'email', 'address', 'update_at',
    ];
}

7-2. Inventory モデル

<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Inventory extends Model
{
    protected $table = 'inventories';

    public $timestamps = false;

    protected $fillable = [
        'product_code',
        'stock_qty',
        'next_arrival_date',
        'arrival_unit_qty',
        'arrival_price',
        'sale_price',
        'update_at',
    ];
}

8) まとめ（初心者向け）

• テーブル作成は Migration の up()
• 初期データは Seeder の run()
• SQLiteは DBファイルが必要（database.sqlite）
• 起動時に整えるは、実務では php artisan migrate:fresh --seed（テスト開始時/環境セットアップ時）

Laravelにおける「初期テーブル作成」と「Webページ表示」の違いと操作方法

1. 全体像（結論を先に）

2. 初期テーブル作成は「環境準備」の作業

SQLiteを使う場合、最初にDBファイルとテーブルを準備する必要があります。
これは Webアクセスとは無関係な「セットアップ作業」です。

2-1. SQLiteファイルを作成（最初の1回のみ）

touch database/database.sqlite

2-2. テーブルを作成する

php artisan migrate

• Migrationクラスの up() が実行される
• users や inventories テーブルが作成される
• Webサーバーは起動しない

2-3. テーブル作成＋初期データ投入（テストでよく使う）

php artisan migrate:fresh --seed

3. Webページを表示するのは「サーバー起動」

テーブル作成が終わった後に、
実際に画面やAPIを利用するために Webサーバーを起動します。

3-1. Webサーバー起動コマンド

php artisan serve

• PHPの簡易Webサーバーが起動する
• デフォルトURL：http://localhost:8000
• DBの作成・変更は一切行われない

4. よくある誤解と正しい理解

❌ 誤解①：serveを叩くとテーブルが作られる

→ 作られません。
serve は Webサーバーを起動するだけです。

❌ 誤解②：migrateを叩かないとWebが見れない

→ ページ自体は表示されますが、DBアクセス時にエラーになります。

✅ 正しい流れ

1. php artisan migrate:fresh --seed（環境準備）
2. php artisan serve（Web表示）

5. テスト環境の場合（サーバーは起動しない）

php artisan test

• Webサーバーは起動しない
• Laravelが内部的にHTTPリクエストを擬似実行
• CIや自動テスト向けの実行方法

6. まとめ（覚えるべきコマンドはこれだけ）

① DB初期化（作成＋初期データ）
php artisan migrate:fresh --seed

② Webページ表示
php artisan serve

③ テスト実行
php artisan test

Laravel（SQLite + Migration + Web）の一般的なプロジェクト構成ツリー

1. プロジェクト全体ツリー（重要部分のみ）

your-project/
├─ app/
│  ├─ Console/
│  │  └─ Kernel.php                # artisanコマンドのスケジューリング定義
│  │
│  ├─ Exceptions/
│  │  └─ Handler.php               # 例外の共通処理（500/404など）
│  │
│  ├─ Http/
│  │  ├─ Controllers/
│  │  │  ├─ Controller.php         # 全Controllerの基底クラス
│  │  │  ├─ UserController.php     # 画面/API用Controller
│  │  │  └─ BillingController.php  # 請求計算API用Controller
│  │  │
│  │  ├─ Middleware/
│  │  │  └─ Authenticate.php       # 認証などの前処理
│  │  │
│  │  └─ Requests/
│  │     ├─ UserUpdateRequest.php  # 入力バリデーション
│  │     └─ BillingRequest.php
│  │
│  ├─ Models/
│  │  ├─ User.php                  # usersテーブルのEntity（Eloquent）
│  │  └─ Inventory.php             # inventoriesテーブルのEntity
│  │
│  ├─ Services/
│  │  ├─ UserService.php           # 業務ロジック層
│  │  └─ BillingService.php
│  │
│  ├─ Repositories/
│  │  ├─ Contracts/
│  │  │  └─ UserRepositoryInterface.php
│  │  └─ Eloquent/
│  │     └─ UserRepository.php     # DBアクセス実装
│  │
│  └─ Providers/
│     └─ AppServiceProvider.php    # DIバインド（Interface → 実装）
│
├─ bootstrap/
│  └─ app.php                      # Laravel起動点（最初に読まれる）
│
├─ config/
│  ├─ app.php                      # アプリ基本設定
│  └─ database.php                 # DB設定（sqlite等）
│
├─ database/
│  ├─ database.sqlite              # SQLite DBファイル（実体）
│  │
│  ├─ migrations/
│  │  ├─ 2026_02_16_000001_create_users_table.php
│  │  └─ 2026_02_16_000002_create_inventories_table.php
│  │
│  ├─ seeders/
│  │  ├─ DatabaseSeeder.php        # Seederの入口
│  │  ├─ UsersSeeder.php           # users 初期データ
│  │  └─ InventoriesSeeder.php     # inventories 初期データ
│
├─ public/
│  └─ index.php                    # Webアクセスの入口（/）
│
├─ resources/
│  ├─ views/
│  │  ├─ users/
│  │  │  ├─ index.blade.php        # 一覧画面
│  │  │  └─ edit.blade.php         # 編集画面
│  │  └─ layout.blade.php
│  │
│  └─ lang/
│     ├─ ja/
│     │  ├─ messages.php           # 日本語メッセージ
│     │  └─ validation.php
│     └─ en/
│        ├─ messages.php
│        └─ validation.php
│
├─ routes/
│  ├─ web.php                      # 画面用ルーティング
│  └─ api.php                      # API用ルーティング（/api プレフィックス）
│
├─ tests/
│  ├─ Feature/
│  │  └─ UserTest.php              # HTTP/APIテスト
│  └─ Unit/
│     └─ BillingServiceTest.php    # 業務ロジック単体テスト
│
├─ .env                            # 環境変数（DB接続など）
├─ artisan                         # artisanコマンド実行ファイル
└─ composer.json                   # PHP依存関係

2. Migration関連ファイルの位置と役割

3. Seeder関連ファイルの位置と役割

4. 「Migration / Seeder」と「Web表示」の関係

• Migration / Seeder：環境を整えるための準備作業
• Controller / View：準備されたDBを使う側
• php artisan serve は Migration を呼ばない

5. 初心者向け一言まとめ

• Migration は「設計図」
• Seeder は「初期サンプルデータ」
• artisan は「それらを実行するための道具」
• serve は「Webを表示するだけ」

Laravel（PHP）入門：Hello, world を表示する（Controller → Service → Blade）

1. このサンプルの完成イメージ

• ブラウザで http://127.0.0.1:8000/hello にアクセスする
• Route（ルーティング）が Controller のメソッドを呼ぶ
• Controller が Service を呼び、メッセージ Hello, world を受け取る
• Controller が Blade（テンプレート）へメッセージを渡して表示する

2. 用語ミニ辞典（初心者向け）

3. VS Code で Laravel プロジェクトを作る（作業手順）

3-1. 作業フォルダを作る

1. 任意の場所にフォルダを作成（例：C:\work）
2. VS Code でフォルダを開く（ファイル → フォルダーを開く）

3-2. ターミナルを開く

• Ctrl+@

3-3. Laravel プロジェクトを作成する

ターミナルで以下を実行します（プロジェクト名は例です）。

cd C:\work
composer create-project laravel/laravel hello-laravel
cd hello-laravel

4. 追加で作るファイル一覧（このサンプルで増えるもの）

routes/
  web.php                     # ルート定義（/hello）

app/
  Http/
    Controllers/
      HelloController.php      # /hello を処理する

  Services/
    HelloService.php           # Hello, world を返す（業務ロジック役）

resources/
  views/
    hello.blade.php            # 画面テンプレ（Hello, world を表示）

5. 具体的なコード（コピペで作れます）

5-1. Route：routes/web.php

/hello にアクセスしたら HelloController@index を呼ぶようにします。

<?php
// routes/web.php

use Illuminate\Support\Facades\Route;          // ルーティング機能
use App\Http\Controllers\HelloController;      // HelloController を使う

// GET /hello へのアクセスを HelloController@index に割り当てる
Route::get('/hello', [HelloController::class, 'index'])
    ->name('hello.index');

5-2. Service：app/Services/HelloService.php

「実務では業務ロジックを書く場所」ですが、今回は練習として Hello, world を返します。

<?php
// app/Services/HelloService.php

namespace App\Services; // このクラスが属する場所（フォルダ構造と一致）

class HelloService
{
    /**
     * 画面に表示するメッセージを返す
     *
     * 実務なら:
     * ・DBから値を取る
     * ・計算する
     * ・ルール判定する
     * などをここに書く
     */
    public function getMessage(): string
    {
        // 今回は固定文字列を返すだけ
        return 'Hello, world';
    }
}

5-3. Controller：app/Http/Controllers/HelloController.php

Controller は HTTPを受ける担当で、Serviceを呼び、Bladeへ渡します。
LaravelのControllerは通常 extends Controller（基底クラス継承）を使います。

<?php
// app/Http/Controllers/HelloController.php

namespace App\Http\Controllers; // Controllerはこの名前空間が基本

use App\Services\HelloService;   // Service を使う
use Illuminate\View\View;        // 戻り値の型（画面）

class HelloController extends Controller
{
    // Service を保持する（DI で注入される）
    private HelloService $helloService;

    /**
     * コンストラクタ（Controllerが作られるときに呼ばれる）
     *
     * DI（依存性注入）により、Laravel が HelloService を自動生成して渡してくれる
     */
    public function __construct(HelloService $helloService)
    {
        $this->helloService = $helloService; // 渡されたServiceを保持
    }

    /**
     * GET /hello の処理
     *
     * 1) Serviceからメッセージを取得
     * 2) Bladeに渡して画面表示
     */
    public function index(): View
    {
        // Serviceからメッセージ取得
        $message = $this->helloService->getMessage();

        // Bladeへ渡して表示
        return view('hello', [
            'message' => $message,
        ]);
    }
}

5-4. Blade：resources/views/hello.blade.php

BladeはHTMLテンプレートです。Controllerから渡された $message を表示します。

<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>Hello</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>

  <h1>{{ $message }}</h1>

</body>
</html>

6. 具体的な作業手順（VS Codeでのファイル作成）

1. VS Code で hello-laravel フォルダを開く
2. routes/web.php を開き、上記の Route を追記する
3. 左のエクスプローラーで app/Services フォルダを作成する（無ければ）
   → その中に HelloService.php を新規作成して貼り付ける
4. app/Http/Controllers に HelloController.php を新規作成して貼り付ける
5. resources/views に hello.blade.php を新規作成して貼り付ける

7. 実行方法（Webページを表示するモード）

7-1. サーバー起動

php artisan serve

7-2. ブラウザでアクセス

http://127.0.0.1:8000/hello

8. よくあるエラー（初心者が詰まるポイント）

8-1. Class not found（クラスが見つからない）

ファイル名・namespace・フォルダ位置が一致していない可能性があります。
例：app/Services/HelloService.php の namespace は App\Services になっているか確認してください。

8-2. 画面が 404 になる

Route が正しく追加されているか確認してください。
routes/web.php に Route::get('/hello', ...) があるか確認します。

9. まとめ

• php artisan serve は「Webを表示する」ための起動コマンド
• Hello表示でも、実務構成に合わせて Controller → Service → Blade に分けられる
• ControllerはHTTP担当、Serviceは業務担当、Bladeは表示担当

PHP の namespace とは？なぜ付けるのか（Laravel前提で理解する）

1. namespace の一言定義

namespace は「クラス名の住所（所属）」です。
同じクラス名でも 住所が違えば別のクラスとして扱えます。

2. 何が困る？（namespace が無い世界）

もし namespace が無い（全クラスが同じ場所に住んでいる）と、
同じクラス名を2つ作れません。

<?php
// namespace が無いと仮定

class User { }        // ① User クラス
class User { }        // ② 同じ名前なのでエラー（再定義）

3. namespace があるとどうなる？（住所が違うので衝突しない）

クラス名が同じでも、namespace（住所）が違えば共存できます。

<?php
namespace App\Models;

class User { }  // App\Models\User

// 別ファイル
namespace App\Dtos;

class User { }  // App\Dtos\User（同名でもOK）

ここでのポイントは、PHP内部ではクラス名は実はこう扱われることです：

• App\Models\User
• App\Dtos\User

つまり「User」ではなく「住所付きの完全な名前」で区別しています。

4. Laravel で namespace を付ける意味（フォルダと一致させる）

Laravel（というか Composer のオートロード）では、
フォルダ構造と namespace が対応するように設定されています（PSR-4）。

5. use は何？（長い住所を短く書く）

namespace を使うと「住所付きの長い名前」になります。
そこで use を使って 別住所のクラスを読み込む（参照する）ようにします。

<?php
namespace App\Http\Controllers;

use App\Services\HelloService; // ← 別住所のHelloServiceを使う宣言

class HelloController extends Controller
{
    public function __construct(private HelloService $helloService) {}
}

use App\Services\HelloService; を書かずに、完全名で書くこともできます：

<?php
namespace App\Http\Controllers;

class HelloController extends Controller
{
    // use を書かない場合は「住所付き」を毎回書く必要がある
    public function __construct(private \App\Services\HelloService $helloService) {}
}

6. よくあるミス（初心者が詰まるポイント）

6-1. ファイル場所と namespace がズレる

app/Services/HelloService.php
namespace App\Service;  ← Services ではなく Service になってる（間違い）

この場合、Laravelは App\Services\HelloService を探しても見つけられず、
Class "App\Services\HelloService" not found のようなエラーになります。

6-2. use の書き忘れ

<?php
namespace App\Http\Controllers;

// use App\Services\HelloService; ← これが無い

class HelloController extends Controller
{
    // HelloService がどこのクラスか分からずエラーになる
    public function __construct(private HelloService $helloService) {}
}

7. まとめ

• namespace＝クラスの「住所」。同名クラスの衝突を防ぐ
• Laravelでは フォルダと namespace を一致させるのが基本
• use＝別住所のクラスを「短く書いて使う」ための宣言

なぜ $this->helloService->getMessage() と書くのか？

1. 前提：Controller は「クラス」から作られた「オブジェクト」

PHP（Laravel）では、Controller は次のような クラス です。

<?php
class HelloController
{
    private HelloService $helloService;

    public function __construct(HelloService $helloService)
    {
        $this->helloService = $helloService;
    }

    public function index()
    {
        $message = $this->helloService->getMessage();
    }
}

このクラスから、Laravel が 実体（オブジェクト）を作ります。

$controller = new HelloController($helloService);

2. $this が無いと何が起きる？

仮に $this を書かずにこう書くとどうなるでしょうか。

// ❌ 間違い
$message = $helloService->getMessage();

PHPはこう考えます：

• 「$helloService という 変数を探す」
• 関数内にそんな変数は存在しない
• → Undefined variable: helloService エラー

3. $this は「今この処理をしている自分」

$this は実行中のメソッドが
「どのオブジェクトの中で動いているか」を示します。

4. なぜコンストラクタで代入しているのか？

public function __construct(HelloService $helloService)
{
    $this->helloService = $helloService;
}

この1行があることで、

• Laravel が作った HelloService を
• Controller のプロパティとして保持できる
• 別のメソッド（index など）からも使える

もし代入しなければ、$helloService は
コンストラクタの中だけで消える変数になります。

5. 図で理解する（イメージ）

HelloController（オブジェクト）
├─ $this
│   ├─ helloService  ──▶ HelloService（オブジェクト）
│   │                    └─ getMessage()
│   └─ index()

6. 静的メソッドとの違い（補足）

もし static メソッドであれば $this は使えません。

class Sample
{
    public static function test()
    {
        // $this は使えない（オブジェクトが無い）
    }
}

今回の Controller / Service は すべてインスタンス（実体）として動くため、
$this を使います。

7. まとめ

• $this は「今のオブジェクト自身」を指す
• クラスのプロパティにアクセスするには必須
• $this->helloService は「この Controller が持っている Service」
• DI と組み合わせると、Controller 全体で Service を使える

return view('hello', ['message' => $message]); の意味

1. 全体を一言で言うと

return view('hello', [
    'message' => $message,
]);

意味を日本語にすると：

2. view() は Laravel の関数ですか？

はい。view() は Laravel が用意しているグローバルヘルパ関数です。

• Laravel本体に最初から含まれている
• Bladeテンプレートを描画するための関数
• Controller から画面を返すときに使う

// Laravelのviewヘルパ
view(string $viewName, array $data = []): View

3. 'hello' は何を指している？

'hello' は Blade ファイル名を指しています。

resources/
└─ views/
   └─ hello.blade.php

Laravel のルールでは：

4. 'message' は Blade 側の変数名ですか？

はい、その通りです。

'message' => $message

これは次の意味を持ちます：

5. Blade 側ではどう使われる？

resources/views/hello.blade.php では、次のように書けます。

<!doctype html>
<html>
<body>

  <h1>{{ $message }}</h1>

</body>
</html>

この {{ $message }} は、

• Controller から渡された
• 'message' => $message
• の message に対応

6. もし配列を渡したら？

return view('hello', [
    'message' => 'Hello',
    'userName' => 'Taro',
]);

Blade 側では：

{{ $message }}   // Hello
{{ $userName }}  // Taro

7. なぜ return しているのか？

Controller の役割は HTTPレスポンスを返すことです。

• view() は「画面オブジェクト」を作る
• return することでブラウザに返す

ブラウザ
  ↑
HTTPレスポンス（HTML）
  ↑
Controller → return view(...)

8. まとめ（初心者向け超要点）

• view() は Laravel 標準の関数
• 'hello' は表示する Blade ファイル名
• 'message' は Blade 側で使う変数名
• $message は Controller 側の値
• Controller → Blade にデータを渡す仕組み

Service が複数ある場合、__construct にはどう書くのか？

1. 基本形（Service が1つの場合）

class HelloController extends Controller
{
    private HelloService $helloService;

    public function __construct(HelloService $helloService)
    {
        $this->helloService = $helloService;
    }
}

これは：

• HelloController が
• HelloService に依存している
• その依存関係を Laravel が自動で注入する

2. Service が複数ある場合の書き方

例えば、次のような Service が必要だとします。

• HelloService（挨拶ロジック）
• UserService（ユーザー処理）
• LogService（業務ログ）

この場合、__construct はこうなります。

class SampleController extends Controller
{
    private HelloService $helloService;
    private UserService $userService;
    private LogService $logService;

    public function __construct(
        HelloService $helloService,
        UserService $userService,
        LogService $logService
    ) {
        $this->helloService = $helloService;
        $this->userService  = $userService;
        $this->logService   = $logService;
    }
}

3. なぜ複数書いても動くのか？（DI の仕組み）

Laravel は Controller を作るとき、内部で次のようなことをしています。

1. HelloController を new したい
2. __construct の引数を見る
3. HelloService が必要だと分かる
4. HelloService をコンテナから取得（なければ生成）
5. 同様に UserService, LogService も解決
6. new HelloController(HelloService, UserService, LogService)

4. よくある疑問①：数が増えすぎたらどうする？

例えば __construct がこうなったら要注意です。

public function __construct(
    AService $a,
    BService $b,
    CService $c,
    DService $d,
    EService $e
) {}

対処法：

• Service をまとめた Facade / Coordinator Service を作る
• 処理を別 Controller に分ける
• Service 同士の責務を整理する

5. PHP8以降の省略記法（プロパティプロモーション）

PHP8 以降では、次のように短く書けます。

class SampleController extends Controller
{
    public function __construct(
        private HelloService $helloService,
        private UserService $userService
    ) {}
}

これは以下と 完全に同じ意味です。

private HelloService $helloService;
private UserService $userService;

public function __construct(
    HelloService $helloService,
    UserService $userService
) {
    $this->helloService = $helloService;
    $this->userService  = $userService;
}

6. よくある誤解

7. まとめ

• 必要な Service は __construct にすべて書いてよい
• Laravel は型ヒントを見て自動注入する
• 多すぎる場合は設計見直しのサイン
• PHP8以降は省略記法も使える

DI されるのは Controller だけですか？

1. なぜ Controller では DI が「当たり前」に見えるのか

Controller で DI が自然に使える理由は、
Laravel が Controller を必ず DI コンテナ経由で生成するからです。

ルーティング
  ↓
Laravel が Controller を生成
  ↓
DI コンテナを使って new する
  ↓
__construct の引数を自動解決

そのため、次のような書き方が普通に動きます。

class HelloController extends Controller
{
    public function __construct(HelloService $helloService)
    {
        // 自動で注入される
    }
}

2. 何も extends しない普通のクラスでも DI される？

はい、されます。
ただし 条件 があります。

3. Service クラスは extends していないが DI されている

典型例が Service クラスです。

class HelloService
{
    public function getMessage(): string
    {
        return 'Hello, world';
    }
}

このクラスは何も extends していませんが、

class HelloController extends Controller
{
    public function __construct(HelloService $helloService)
    {
        // ここに注入される
    }
}

問題なく DI されます。

4. DI されないケース（重要）

次のように new したクラスは DI されません。

// ❌ DIされない
$service = new HelloService();

これは PHP が直接インスタンスを作っているため、
Laravel の DI コンテナが関与できないからです。

5. 一般クラスを DI したいときの正しい流れ

例えば、業務用クラスを作った場合：

class PriceCalculator
{
    public function calc(int $price): int
    {
        return $price * 2;
    }
}

これを DI したい場合：

class BillingService
{
    public function __construct(
        PriceCalculator $calculator
    ) {
        // DIされる
    }
}

BillingService が DI コンテナ経由で生成される限り、
PriceCalculator も自動的に DI されます。

6. 「DIされるかどうか」の判断基準

7. まとめ（初心者向け超重要）

• DI は「Controller だから」行われるわけではない
• Laravel が管理して生成するクラスは DI される
• extends の有無は関係ない
• new すると DI は効かない
• 「誰が new しているか」が判断基準

DTO や Entity も自動生成（DI）されるのか？

1. まず結論を表で整理

2. なぜ Service は DI されるのか？

class UserService
{
    public function doSomething() {}
}

class UserController extends Controller
{
    public function __construct(
        UserService $userService
    ) {
        // ← DIされる
    }
}

Service は：

• 「処理・ロジック」を持つ
• 状態を持たない（または少ない）
• 再利用される

そのため DI コンテナが管理する対象になります。

3. DTO はなぜ DI されないのか？

class UserDto
{
    public function __construct(
        public string $name,
        public string $email
    ) {}
}

DTO（Data Transfer Object）は：

• 単なるデータの箱
• 処理ロジックを持たない
• 毎回中身が違う

そのため DTO は普通、こう使います。

// 自分で new する（正しい）
$dto = new UserDto(
    name: 'Taro',
    email: 'taro@example.com'
);

4. Entity（Model）はなぜ DI されないのか？

class User extends Model
{
    protected $table = 'users';
}

Entity（Eloquent Model）は：

• DB の1行を表す
• レコードごとに中身が違う
• 「生成される」というより「取得される」

// DBから取得される
$user = User::find(1);

5. 質問のコードの誤りを修正

質問にあったコードを PHP/Laravel 的に直します。

❌ Java風・誤解がある例

public class Service {
    private Service $service; // ← これはおかしい
}

✅ 正しい Service の依存関係

class OrderService
{
    public function __construct(
        UserRepository $userRepository,
        PriceCalculator $calculator
    ) {
        // これらは DI される
    }
}

Service は「別の Service / Repository」に依存します。

6. まとめ（超重要）

• DI されるのは「処理を持つクラス」
• DTO はデータの箱 → DI しない
• Entity は DB の1行 → DI しない
• Service / Repository は DI する
• 「毎回中身が変わるもの」は DI しない

Laravel は「どこを見て」DI が動作するか決めているのか？

1. DI が動作する条件（これだけ）

Laravel の DI（Service Container）が動作するのは、
次の条件を満たすクラスです。

まとめると：

2. Laravel が実際にやっている処理（概要）

Laravel は、DI 対象のクラスを生成するときに、
内部で次の処理を行っています。

① コンテナに「このクラスを作って」と依頼される
② コンストラクタ (__construct) を調べる
③ 引数があれば、それぞれ解決できるか確認する
④ すべて解決できたら new する

この処理は 再帰的に行われます。

3. コードで見る DI が動作する例

class HelloService
{
    // コンストラクタなし
}

class HelloController
{
    public function __construct(
        HelloService $helloService
    ) {}
}

この場合：

HelloController を作る
↓
HelloService が必要と分かる
↓
HelloService は引数なしで new できる
↓
DI が成立する

4. クラスの種類は判断材料ではない

DI が動作するかどうかは、次の要素とは関係ありません。

• Controller かどうか
• Service かどうか
• DTO / Entity かどうか
• extends しているかどうか
• プロパティを持っているかどうか

5. まとめ（事実のみ）

• Laravel はクラスの種類で DI を判断しない
• 見ているのはコンストラクタだけ
• 引数なしで new できる形なら DI は動作する
• プロパティの有無や初期値は判断材料ではない

PHP / Laravel のログ出力：デバッグ用（コンソール）と本番用（ログファイル）の使い分け

1. 大前提：Laravel のログは Log ファサードで出す

Laravel では、ログ出力は Illuminate\Support\Facades\Log を使います。
これは「ログの出力先（ファイル / 標準出力 / その他）」を設定で切り替えられる仕組みになっています。

<?php

use Illuminate\Support\Facades\Log;

Log::debug('debug message');   // 開発中の細かい情報（本番では出さないことが多い）
Log::info('info message');     // 通常運用の記録
Log::warning('warn message');  // 想定外だが継続できる状態
Log::error('error message');   // エラー（原因調査が必要）

2. デバッグ時：C の printf 相当は「ログ」または「画面 dump」

2-1. まずはログで出す（おすすめ）

C の printf() のように「ここ通った」「値が何か」を確認したい場合、
Laravel では Log::debug() で出すのが安全です。

<?php

use Illuminate\Support\Facades\Log;

public function calc(Request $request)
{
    $payload = $request->all();

    // printf 相当：入力をログに出す
    Log::debug('[Billing] input payload', [
        'payload' => $payload,
    ]);

    // 何か計算した結果
    $result = ['ok' => true];

    // 結果もログへ
    Log::debug('[Billing] result', [
        'result' => $result,
    ]);

    return response()->json($result);
}

2-2. 画面に出す（dd / dump）＝開発中だけ

C の printf で画面に出す感覚に近いのが dd()（Dump and Die）です。
ただしこれは 処理を止めるので、開発中だけにします。

// 開発中だけ：値を表示して処理停止
dd($payload);

// 表示して止めない（Laravel の dump）
dump($payload);

3. 「デバッグ時のコンソールログ」と「本番のログファイル」

3-1. 開発時：コンソールに出したい（stdout）

開発時に「ターミナル（コンソール）で見たい」場合、Laravel のログ出力先を stderr/stdout にできます。
典型例は Docker や CI で、コンテナログに流したい場合です。

Laravel のログ出力先は .env の LOG_CHANNEL で切り替えます。

# 開発：コンソールに流す例
LOG_CHANNEL=stderr
LOG_LEVEL=debug

※ 実際の利用可否は Laravel バージョンや config/logging.php の定義に依存します。
ただ、考え方は「ログは設定で出力先を変えられる」です。

3-2. 本番：ログファイルに残す（重要）

本番運用では「あとで原因調査できるように」ログをファイルに残します。
Laravel の標準では、storage/logs/laravel.log に出力されます。

# 本番：ファイルに残す（一般的な例）
LOG_CHANNEL=stack
LOG_LEVEL=info

4. 「使い分け」の実例（デバッグ用 / 本番用）

開発中は「値を見る」ために debug を多用しますが、
本番では「後から追える情報」に絞って info / warning / error を出します。

<?php

use Illuminate\Support\Facades\Log;

public function update(Request $request, int $id)
{
    // 開発中：入力値を見たい（本番では出さないことが多い）
    Log::debug('[UserUpdate] request received', [
        'id' => $id,
        'email' => $request->input('email'),
        'tel' => $request->input('tel'),
    ]);

    try {
        // 何らかの更新処理（例）
        // $this->service->update(...);

        // 本番：更新成功の記録（調査に使える）
        Log::info('[UserUpdate] updated', [
            'id' => $id,
        ]);

        return response()->json(['ok' => true]);

    } catch (\Throwable $e) {

        // 本番：例外は error で必ず残す
        Log::error('[UserUpdate] failed', [
            'id' => $id,
            'error' => $e->getMessage(),
        ]);

        return response()->json(['ok' => false], 500);
    }
}

5. まとめ（C の printf と比較して）

• C の printf() 相当 → Laravel なら Log::debug()（安全）
• 画面に出す → dd() / dump()（開発中だけ）
• 本番はログファイル（またはコンテナログ）に残す
• ログの出力先やレベルは .env で切り替える