bagisto-package-development

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/{23 locales}/, assets/
└── Routes/           # web.php (api.php for API routes)

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.