bagisto-package-development

Bagisto でのパッケージ開発

Bagisto のパッケージは、packages/Webkul/<Name>/ に置かれる自己完結型の Laravel モジュールです。 コアパッケージは共通のレイアウトを基にしていますが、必要な部分だけを取り入れます。 汎用的な Laravel パッケージを新規作成するのではなく、最も近い既存のパッケージをコピーしてください。

参照ファイル — 現在のタスクに必要なものだけを読み込む

ファイル	読み込むタイミング
core.md	パッケージを作成するとき — ディレクトリ構成、composer.json、プロバイダー、Concord の登録
data-layer.md	マイグレーション、モデル、コントラクト、プロキシ、リポジトリ
ui.md	ルート、コントローラー、Blade ビュー
features.md	管理メニュー、ACL、システム設定

パッケージの構成

packages/Webkul/<Name>/src/
├── Config/           # system.php, admin-menu.php, acl.php
├── Contracts/        # one interface per model
├── Database/         # Migrations/, Seeders/, Factories/
├── DataGrids/        # admin listings
├── Http/Controllers/ # separate Admin/ and Shop/
├── Models/           # Eloquent models + Proxy classes
├── Providers/        # <Name>ServiceProvider + ModuleServiceProvider
├── Repositories/     # all database access
├── Resources/        # views/, lang/{23 locales}/, assets/
└── Routes/           # web.php (api.php for API routes)

ほとんどのパッケージにはこの一部しか含まれませんが、それは意図的なものです。 すべてのパッケージに共通するのは Providers/ だけです。コアパッケージのうち、およそ 25 個には Contracts/Models/Repositories が、14 個には Config/ が、11 個には Http/Controllers/ が、8 個には Routes/ が含まれています。UI の 3 要素すべてを持つのは、Admin、Shop、および決済ゲートウェイ（Stripe、PayU、Razorpay、PayGlocal、PhonePe）の数パッケージだけです。

Category、CartRule、CMS、Marketing のようなドメインパッケージは、コントラクト、モデル、リポジトリだけのデータレイヤーです。管理画面は Admin に、ストアフロントのページは Shop に置きます。決済ゲートウェイのように、その機能が独自のルートを本当に所有するのでない限り、これらのパッケージに Routes/ や Http/Controllers/ を追加しないでください。どのディレクトリが必要かを決める前に、最も近い既存のパッケージを確認してください。

譲れないルール

• 二重登録。 すべてのパッケージは 2 か所に登録します。メインの ServiceProvider は bootstrap/providers.php に、ModuleServiceProvider は config/concord.php に登録します。どちらか一方でも漏れると、パッケージの一部だけが読み込まれ、原因の特定が難しくなります。core.md を参照してください。
• モデルの 3 要素。 すべてのエンティティは、コントラクト、それを実装するモデル、プロキシで構成されます。リポジトリの model() は コントラクト を返し、パッケージをまたぐ型指定には プロキシ を使います。これにより、コアを編集せずにモデルを置き換えられます。data-layer.md を参照してください。
• Docblock、メンバーの順序、コメント、リポジトリのルール、翻訳は、bagisto-coding-standards スキルが管理します。これらはパッケージだけでなく、Bagisto のすべてのファイルに適用され、レビューで最もよく却下される原因です。
• 変更した箇所は修正する。 編集するファイルに既存の違反があれば、それもあなたの責任です。自分が追加した行だけでなく、クラス全体のメンバー順序と Docblock を確認してください。

関連スキル

• bagisto-coding-standards — Docblock、メンバーの順序、コメント、リポジトリアクセス、ローカライズ。 PHP を扱う場合は、このスキルと併せて読み込んでください。
• bagisto-datagrid-development — 管理画面の一覧ページ。features.md では DataGrid の概要を説明していますが、 列、フィルター、アクション、エクスポート、およびセキュリティルールについてはこのスキルが管理します。
• bagisto-coding-standards — Blade レイヤーも対象です。パッケージを問わず、あらゆる .blade.php が対象です。
• bagisto-pest-testing / bagisto-playwright-testing — 作成したもののテスト。
• bagisto-change-verification — 完了判定の基準。

必須のサブスキル： 変更を完了とする前に、bagisto-change-verification を使用してください。