blocs/admin: 定義ファイルの作成と管理画面の自動生成

blocs/admin: 定義ファイルの作成と管理画面の自動生成

自動生成ツールは、JSON形式の定義ファイルをもとに管理画面のコントローラー・ビュー・ルーティング・モデル・マイグレーションを一括生成します。このドキュメントでは、定義ファイルの書き方と自動生成コマンドの使い方を説明します。

前提条件: blocs/admin がインストール済みであること（No.1.1 を参照）

自動生成の実行方法

1. 定義ファイルの作成

JSON形式の定義ファイルを docs/develop/ に保存します（例: docs/develop/sample.json）。

2. Artisan コマンドの実行

php artisan blocs:develop docs/develop/sample.json

コマンド実行時に自動で行われる処理

• ベースコントローラーを継承したコントローラー生成
• routes/web.php へのルート追加（標準管理画面のルートは routes/admin.php。自動生成画面のみ web.php に追記される）
• config/menu.php へのメニュー追加
• モデル生成
• データベース定義ファイル生成
• マイグレーション実行
• テンプレート生成

php artisan migrate を別途実行する必要はありません。

自動生成後に利用できる基本機能

定義ファイルの形式（JSON）

定義ファイルは以下の4つのセクションで構成されます。

controller セクション

controllerName と modelName は Admin/ プレフィックス付き（例: Admin/SampleController）を推奨します。サブ名前空間なし（例: CompanyController）も動作しますが、生成先の名前空間と一致させてください。

form セクション

フォーム名をキーとした連想配列で、各入力項目を定義します。

テキスト入力タイプ（text, textarea, datepicker, timepicker, number）

選択入力タイプ（select, radio, checkbox）

検索できるプルダウン（select2）

ファイルアップロード（upload）

option の記述形式

option は次の2形式のいずれかで記述します。

入力タイプ一覧

menu セクション

route セクション

サンプル: 企業情報の管理画面

{
  "controller": {
    "controllerName": "CompanyController",
    "viewPrefix": "admin.company",
    "modelName": "Company",
    "loopItem": "companies",
    "paginateNum": 20,
    "noticeItem": "name"
  },
  "form": {
    "code": {
      "label": "証券番号",
      "type": "text",
      "required": true
    },
    "name": {
      "label": "名前",
      "type": "text",
      "required": true
    }
  },
  "menu": {
    "name": "admin.company.index",
    "lang": "企業",
    "icon": "fa-building"
  },
  "route": {
    "routePrefix": "admin/company",
    "routeName": "admin.company."
  }
}

サンプル: ソリューション管理画面（ステータス・選択肢あり）

{
  "controller": {
    "controllerName": "Admin/SolutionController",
    "viewPrefix": "admin.solution",
    "modelName": "Admin/Solution",
    "loopItem": "solutions",
    "paginateNum": 20,
    "noticeItem": "name"
  },
  "form": {
    "disabled_at": {
      "label": "ステータス",
      "type": "radio",
      "option": {
        "0": "有効",
        "1": "無効"
      },
      "default": "0",
      "required": true
    },
    "name": {
      "label": "名前",
      "type": "text",
      "required": true
    },
    "pattern": {
      "label": "パターン",
      "type": "select",
      "option": {
        "A": "パターンA",
        "B": "パターンB"
      },
      "required": true
    }
  },
  "menu": {
    "name": "admin.solution.index",
    "lang": "ソリューション",
    "icon": "fa-tag",
    "role": true
  },
  "route": {
    "routePrefix": "admin/solution",
    "routeName": "admin.solution."
  }
}

QA

入力フォームを必須項目にしたい場合

BLOCS テンプレートでは data-validate（省略記法 !name）でバリデーションを指定します（詳しくは No.2.10 を参照）。

<input type="text" name="name">
<!-- !name="required" data-lang="必須入力です。" -->
@error("name")
<div class="invalid-feedback">{{ $message }}</div>
@enderror

自動生成ルートのミドルウェア

blocs:develop が routes/web.php に追記するルートテンプレート（develop/route.php）は、['auth', Blocs\Middleware\Role::class] のみを指定します。web は含めません。

Laravel は routes/web.php に登録されたルートへ web ミドルウェア（セッション・Cookie・CSRF 保護）を自動付与します。テンプレート側で web を追加すると二重に適用されるため、付けないでください（No.1.2 参照）。

一方、同梱の routes/admin.php は AdminServiceProvider の loadRoutesFrom() で読み込まれるため web は自動付与されません。こちらは各ルートグループで ['web', 'auth', ...] と 明示的に web を指定してください。