Package Development in Bagisto
A Bagisto package is a self-contained Laravel module under packages/Webkul/<Name>/.
Core packages draw from one shared layout but take only the parts they need —
copy the closest existing package rather than scaffolding a generic Laravel one.
Reference files — load only what the current task needs
| File |
Load when |
| core.md |
Creating a package — directory layout, composer.json, providers, Concord registration |
| data-layer.md |
Migrations, models, contracts, proxies, repositories |
| ui.md |
Routes, controllers, Blade views |
| features.md |
Admin menus, ACL, system configuration |
The shape of a package
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/{22 locales}/, assets/
└── Routes/ # admin-routes.php, shop-routes.php
Most packages carry only part of this, and that is deliberate. Only
Providers/ is universal. Of the core packages, roughly 25 have
Contracts/Models/Repositories, 14 have Config/, 11 have
Http/Controllers/ and 8 have Routes/ — and the handful with all three
UI pieces are Admin, Shop and the payment gateways (Stripe, PayU,
Razorpay, PayGlocal, PhonePe).
A domain package such as Category, CartRule, CMS or Marketing is a
data layer only — contracts, models and repositories. Its admin screens live
in Admin, its storefront pages in Shop. Do not add Routes/ or
Http/Controllers/ to one of those unless the feature genuinely owns its own
routes, as a payment gateway does. Check the closest existing package before
deciding which directories yours needs.
The rules that are not negotiable
- Dual registration. Every package registers twice: its main
ServiceProvider in bootstrap/providers.php, and its ModuleServiceProvider
in config/concord.php. Miss either and the package half-loads in a way that
is hard to diagnose. See core.md.
- Three-part models. Every entity is a Contract, a Model implementing it, and
a Proxy. Repositories return the Contract from
model(), and cross-package
type hints use the Proxy — that is what makes a model replaceable without
editing core. See data-layer.md.
- Docblocks, member order, comments, the repository rule and translations
are owned by the
bagisto-coding-standards skill. They apply to every Bagisto
file, not only to a package, and they are the most common review rejection.
- Fix what you touch. A pre-existing violation in a file you edit is yours:
scan the whole class's member order and docblocks, not just your own lines.
Related skills
bagisto-coding-standards — docblocks, member order, comments, repository access,
localization. Load it alongside this one for any PHP.bagisto-datagrid-development — admin listing pages. features.md sketches the
DataGrid; that skill owns columns, filters, actions, export and the security
rules.bagisto-coding-standards — including the Blade layer: any .blade.php, in any package.bagisto-pest-testing / bagisto-playwright-testing — tests for what you build.bagisto-change-verification — the completion gate.
REQUIRED SUB-SKILL: Use bagisto-change-verification before calling any change done.
1---2name: bagisto-package-development3description: Use when creating or changing a Bagisto package — service providers, migrations, models, contracts, proxies, repositories, routes, controllers, Blade views, localization, admin menus, ACL or system configuration. Trigger phrases include "new package", "service provider", "migration", "model", "repository", "controller", "route", "ACL", "admin menu", "system config", "concord".4license: MIT5---67# Package Development in Bagisto89A Bagisto package is a self-contained Laravel module under `packages/Webkul/<Name>/`.10Core packages draw from one shared layout but take only the parts they need —11copy the closest existing package rather than scaffolding a generic Laravel one.1213## Reference files — load only what the current task needs1415| File | Load when |16|---|---|17| [core.md](core.md) | Creating a package — directory layout, `composer.json`, providers, Concord registration |18| [data-layer.md](data-layer.md) | Migrations, models, contracts, proxies, repositories |19| [ui.md](ui.md) | Routes, controllers, Blade views |20| [features.md](features.md) | Admin menus, ACL, system configuration |2122## The shape of a package2324```25packages/Webkul/<Name>/src/26├── Config/ # system.php, admin-menu.php, acl.php27├── Contracts/ # one interface per model28├── Database/ # Migrations/, Seeders/, Factories/29├── DataGrids/ # admin listings30├── Http/Controllers/ # separate Admin/ and Shop/31├── Models/ # Eloquent models + Proxy classes32├── Providers/ # <Name>ServiceProvider + ModuleServiceProvider33├── Repositories/ # all database access34├── Resources/ # views/, lang/{22 locales}/, assets/35└── Routes/ # admin-routes.php, shop-routes.php36```3738**Most packages carry only part of this, and that is deliberate.** Only39`Providers/` is universal. Of the core packages, roughly 25 have40`Contracts/Models/Repositories`, 14 have `Config/`, 11 have41`Http/Controllers/` and 8 have `Routes/` — and the handful with all three42UI pieces are `Admin`, `Shop` and the payment gateways (`Stripe`, `PayU`,43`Razorpay`, `PayGlocal`, `PhonePe`).4445A domain package such as `Category`, `CartRule`, `CMS` or `Marketing` is a46**data layer only** — contracts, models and repositories. Its admin screens live47in `Admin`, its storefront pages in `Shop`. Do not add `Routes/` or48`Http/Controllers/` to one of those unless the feature genuinely owns its own49routes, as a payment gateway does. Check the closest existing package before50deciding which directories yours needs.5152## The rules that are not negotiable5354- **Dual registration.** Every package registers twice: its main55 `ServiceProvider` in `bootstrap/providers.php`, and its `ModuleServiceProvider`56 in `config/concord.php`. Miss either and the package half-loads in a way that57 is hard to diagnose. See [core.md](core.md).58- **Three-part models.** Every entity is a Contract, a Model implementing it, and59 a Proxy. Repositories return the **Contract** from `model()`, and cross-package60 type hints use the **Proxy** — that is what makes a model replaceable without61 editing core. See [data-layer.md](data-layer.md).62- **Docblocks, member order, comments, the repository rule and translations**63 are owned by the **`bagisto-coding-standards`** skill. They apply to every Bagisto64 file, not only to a package, and they are the most common review rejection.65- **Fix what you touch.** A pre-existing violation in a file you edit is yours:66 scan the whole class's member order and docblocks, not just your own lines.6768## Related skills6970- **`bagisto-coding-standards`** — docblocks, member order, comments, repository access,71 localization. Load it alongside this one for any PHP.72- **`bagisto-datagrid-development`** — admin listing pages. `features.md` sketches the73 DataGrid; that skill owns columns, filters, actions, export and the security74 rules.75- **`bagisto-coding-standards`** — including the Blade layer: any `.blade.php`, in any package.76- **`bagisto-pest-testing`** / **`bagisto-playwright-testing`** — tests for what you build.77- **`bagisto-change-verification`** — the completion gate.7879**REQUIRED SUB-SKILL:** Use bagisto-change-verification before calling any change done.
bagisto