Bagisto Standard Laravel Package

Getting Started

This is a project skeleton, not a package you install into an app. bagisto/bagisto-standard is the laravel/laravel of a Bagisto storefront: it bundles the Bagisto core packages (packages/Webkul/*), default config, and a ready-to-run directory layout. If you composer require this into an existing Laravel app, you've misread it. The only two valid entry points are composer create-project or reading it as a reference template.

The first decision is the archived-repo reality. Last release was 2020-07-06, the repo is archived, it has 10 stars and 0 dependents, and the only published change in that release was a composer install fix. For anything revenue-bearing today, scaffold from the currently maintained Bagisto distribution and pin versions. Use this repo only to read the shape of a Bagisto app — module layout, config merges, theming — before you scaffold. Reproduce or migrate a legacy v0.x / v1.0-era install from it only if you must, and treat every command as archaeology rather than a baseline.

Minimal stand-up (v1.0-era skeleton):

composer create-project bagisto/bagisto-standard my-store
cd my-store
cp .env.example .env
php artisan key:generate
php artisan storage:link
# set DB creds in .env first, then:
php artisan migrate --seed

If composer install fails on platform requirements — expected, given the pinned PHP 7.x / Laravel 7–8-era constraints — resist --ignore-platform-reqs as a permanent fix. It hides a real mismatch that surfaces later as a runtime fatal. Later Bagisto releases ship a bagisto:install command; do not assume it exists in this snapshot.

Where to look first, in order:

1. packages/Webkul/ — the entire platform (Admin, Shop, Customer, Product, Checkout, Payment, Shipping, Tax, Sales, Core, plus the Velocity storefront theme). You will spend ~90% of your reading time here.
2. packages/Webkul/Core/src/Config/ and config/ — every behavior toggle, channel, and module registration.
3. packages/Webkul/Admin/src/Http/routes.php and the matching Resources/views — how admin screens are actually wired.
4. concord.php and module config files — the repository/contract bindings that make Bagisto "modular." Understand these before you override anything.
5. composer.json + composer.lock — the version reality check. Read the lockfile before you plan any work.

First use case worth doing: add a custom attribute to the product admin form and persist it end to end. It forces you through migration → model/repository → admin form Blade → datagrid → validation — exactly the loop you will repeat for every feature. Log in at /admin with the seeded admin account and confirm the storefront renders at / before touching code.

Implementation Patterns

Confine all customization to your own namespace. Create packages/Webkul/{YourVendor}/{YourPackage}/ with a composer.json (PSR-4 autoload), a service provider, and Concord module registration. Register the provider in config/app.php (or via composer.json autoload plus composer dump-autoload). Everything you build lives there. This is also what keeps your upgrade delta a diff rather than an excavation.

Extend through Concord contracts, never concrete classes. Bagisto resolves models through interfaces. To extend a product, subclass it and rebind the contract instead of editing Webkul\Product\Models\Product:

// config/concord.php or your module's concord config
'modules' => [
    \Webkul\Product\Providers\ModuleServiceProvider::class => [
        \Webkul\Product\Contracts\Product::class => \App\Shop\Product::class,
    ],
],

Resolve through the repository (Concord::getRepository(ProductRepository::class)), never new Product. Verify the binding with a dump in php artisan tinker. A silently unbound contract is the most common "my override does nothing" bug in this codebase.

Admin datagrids are declarative. List screens are defined by a datagrid class: columns, actions, mass actions, filters. Adding a column means editing the datagrid class plus the query that feeds it — not the Blade. Copy an existing small datagrid as the template; the shape is consistent across packages.

Menu entry + ACL is a two-file commit. A new admin screen needs both a menu entry (Admin package menu config) and an ACL node in acl.php, or authorized users see a 403 on a route that exists. Ship both in the same PR.

Payment and shipping gateways extend abstract base classes. Implement authorize/capture/refund (payment) or rate calculation (shipping), and register in the respective methods config. Keep the gateway class thin — validation and signature checking belong there, business rules about when a method is offered belong in config or a listener. Provider sandboxes call your webhook route directly, so it must be CSRF-exempt and publicly reachable; test it through a tunnel, not localhost.

Use events for integration, not model hooks. Order placement, shipment creation, and refunds emit events. Wire ERP/PIM/analytics pushes as queued listeners rather than editing checkout controllers. This keeps your revenue path unmodified, downgrade-safe, and replayable when an external system is down.

Override Blade in the theme's resource path, not in place. For the Velocity storefront, asset changes require the Node build toolchain — a Blade-only change may still need a rebuild if the theme compiles assets. Check before concluding your change "isn't showing."

Local dev loop after adding a package or changing providers:

composer dump-autoload
php artisan config:clear && php artisan cache:clear && php artisan view:clear && php artisan route:clear

Keep that as a Makefile target. Most "my change isn't picked up" reports in Bagisto are stale config or view caches, not code.

Headless and multi-channel boundaries. If a separate storefront is on the roadmap, the REST/GraphQL surface is the boundary. Decide now whether commerce is a monolith you extend or a service you call — retrofitting that boundary later means untangling Blade-coupled checkout logic, the most expensive refactor in the codebase.

Gotchas and Tips

The archived-repo reality dominates everything else. Last release 2020-07-06, no maintainer, 0 dependents. You own all maintenance permanently. Budget it as a standing fraction of an engineer, and remember self-hosted checkout is PCI-adjacent — stale payment SDKs are a security review gate, not a backlog item.

composer.lock is sacred. A blind composer update on a 2020 lockfile resolves transitive deps to versions that break the app in non-obvious ways (signature changes, removed helpers, type tightening). Pin explicitly. Move one package at a time and run the app after each bump.

packages/Webkul/* is editable — that is the trap. In-tree modules mean nothing stops you from editing core, and every edit is a merge conflict on the next upgrade. Prefer overrides first, patches second (keep a patches/ directory or git-tracked diff), edits never.

Config cache resurrects old bindings. If config:cache was run and you then change a Concord binding or module provider, the cache wins. Always config:clear in development; never cache config in a workflow that changes bindings.

The Node build toolchain is a hidden prerequisite. The Vue admin and storefront theme need the specific Node/npm version from a 2020-era package.json. Modern Node fails on old node-sass binaries. Pin Node via .nvmrc or a container image and expect an afternoon lost before your first asset change.

Catalog search degrades sharply without a search engine. Blade/LIKE search and faceting are fine to a few thousand SKUs and painful beyond. Confirm Elasticsearch/OpenSearch availability before the catalog import, not after facet latency complaints.

Queue workers are not optional. Indexers, emails, and integration listeners assume a running worker. A dev environment without php artisan queue:work produces "nothing happens" reports that look like bugs. Mirror the production queue driver locally — a sync driver masks ordering and retry bugs until deploy.

Storage and images. storage:link and the media disk config are required; thumbnails are cached, so after changing an image or size config, clear the cache or chase a phantom. For S3-backed media, verify URL and ACL config per environment — this breaks between dev and prod more often than any other config.

Multi-store, multi-currency, multi-locale are on by default. They add a channel dimension to almost every query. If you have one channel, verify you're not paying complexity for capability you'll never use — and if you do need them, set APP_URL and per-channel hostnames correctly, or sessions and admin redirects bounce between domains in ways that look like auth bugs.

Debugging toolkit: php artisan route:list | grep admin to confirm a route registered; php artisan tinker with Concord::getRepository(...) to confirm a binding; the ACL config to confirm a 403 is permission rather than routing; structured logs on the queue worker for anything integration-shaped. Put your dd() in the repository, not the controller — the controller is usually innocent.

Extension points, in order of preference: a Concord contract rebind → an event listener → a view/config override → a documented patch to core. Anything below that line is debt you write today and repay at upgrade time. Given this artifact's vintage, the upgrade bill arrives sooner than you think.