Bagisto Package Generator Laravel Package

Getting Started

Install it as a dev dependency in the host Bagisto application — never in a package's own composer.json, and never in production:

composer require --dev bagisto/bagisto-package-generator
php artisan list | grep package      # confirm the exact command signature for your version
php artisan package:make --help      # check available flags before scripting anything

Run the generator interactively the first time and answer the prompts (vendor, package, author name, author email, description). It writes a Bagisto-shaped skeleton into packages/<Vendor>/<Package>/ with a service provider, composer.json, route files, config files (acl.php, system.php, admin menu), migrations, controllers, views and language files.

Where to look first. Two places, in this order:

1. The emitted tree. find packages/Acme/Blog -type f | sort — read every file once before writing a line of your own code. You need to know what you did not write, because it is now your code.
2. The stubs. find vendor/bagisto/bagisto-package-generator -maxdepth 2 -type d and open the stub/template directory. The stubs are the whole product; reading them tells you exactly what the tool will and won't produce far faster than generating variants.

First real use case. Scaffold one throwaway package and diff it against the strongest hand-written package already in your repo:

php artisan package:make            # Acme / Blog
diff -r packages/Acme/Blog packages/Webkul/ExistingPackage

Then delete it. Do this before you commit to the tool — a one-hour spike surfaces every convention mismatch while it's still free to walk away.

After generating for real:

composer dump-autoload
php artisan optimize:clear
php artisan migrate

Verify two wiring points manually: a psr-4 entry for Acme\Blog\ in the root composer.json, and the provider registered where your Bagisto version keeps providers (config/app.php or bootstrap/providers.php). If either is missing, you get a silent "class not found" that looks like a generator bug but is a registration gap.

Implementation Patterns

Treat the generator as step one of three: scaffold, prune, implement. The most common failure mode is leaving every generated file in place. Delete the route files you don't use, the empty console command, the unused config blocks, and the empty test stubs. A package with six empty tests reads as coverage to a reviewer skimming the PR.

Naming discipline up front. Vendor and Package are PascalCase directory names and namespace segments. Pick Acme / Blog → Acme\Blog → composer name acme/blog and never deviate. Decide this per organization and write it in the handbook; the tool will happily let two teams pick different vendors for the same product area.

Bagisto-specific wiring is the part worth reviewing. In a generated package, the files most likely to be wrong or incomplete for your case are:

• acl.php — admin permission keys must match the route names you actually expose, or the menu item renders but 403s.
• system.php — admin configuration groups; every field needs a complete info / title shape or the admin config page errors (v2.1.2 fixed exactly this class of bug upstream).
• Admin menu config — the nav item's route must resolve.
• Payment-method scaffolds — v2.1.2 corrected a file-convention bug here; if you generate a payment method, verify the class name matches the filename and that the method actually appears in checkout config.

Workflow that holds up day to day:

git checkout -b feature/blog-package
php artisan package:make            # generate
git add packages/Acme/Blog && git commit -m "chore: scaffold blog package"
# ...now edit. The scaffold commit is your diff baseline and your revert point.

That first commit is the single highest-value habit here: when the tool misbehaves or you need to regenerate after a core upgrade, git diff against the scaffold commit tells you precisely what the generator changed versus what you wrote.

Extraction path. Bagisto apps are typically monorepos of packages/. Start the package in-tree; when it stabilises and a second app needs it, move it to its own repository and pull it back in via a Composer VCS/path repository. Do not start with a separate repo — it costs you the fast edit loop for no benefit during development.

Non-interactive use, if flags exist in your version. Generating in a script or a container entrypoint is fine for scaffolding, but never wire package:make into CI or a deploy pipeline. It's a developer command; the generated output is source code that must be reviewed and committed like anything else.

Gotchas and Tips

• Generated code is a draft, not a correct-by-construction artifact. The 2.1.2 release notes are the evidence: a payment-method file convention fix, a missing info key that caused an error, and syntax updates. Assume any given path in the stubs may be subtly wrong for your core version. Review the diff; don't trust the tree.

• Version-pin it. "bagisto/bagisto-package-generator": "~2.1.0" in require-dev. The tool encodes assumptions about Bagisto core, so an unpinned update can change output under you mid-sprint.

• Regenerate and diff on every Bagisto upgrade. Build a throwaway package, diff the tree against the last one you generated, and read the delta. Add this as a line in the core-upgrade runbook — roughly half a day — rather than leaving it as tribal knowledge held by whoever adopted the tool.

• Missing autoload entry is the #1 "it's broken" report. If Acme\Blog\Providers\BlogServiceProvider isn't found, check the root composer.json psr-4 map and run composer dump-autoload before debugging anything else. Similarly, cleared caches fix most "the admin menu item isn't there" reports: php artisan optimize:clear.

• Case sensitivity bites on cross-platform teams. packages/Acme/Blog with namespace Acme\Blog works on macOS and fails on Linux CI if a segment is miscased. Commit the directory names the generator produced rather than hand-retyping them.

• Don't re-run on an existing package directory without committing first. Regeneration can overwrite your edits. Commit, then generate, then diff — never the other way round.

• Empty route files still register. An unused admin-routes.php with no routes is harmless; one with a leftover stub route is not. Prune deliberately.

• Delete or fill the stub tests. A skeleton with no tests is honest; a skeleton with six passing empty tests is misleading. Require at least one meaningful test before calling a package done.

• Extension points, in order of value: fork the stubs (they're templates, not logic — a few days a year to own), pin the version, and keep a short internal "how we create a package" note that references the scaffold output. Don't fork the command logic unless you're changing behaviour.

• Scope guard. The tool makes packages cheap, which inflates the number of modules a core upgrade can break. Pair adoption with a lightweight review question — does this need a new package, or does it belong in an existing one? — and track package count per quarter as a sprawl indicator, not a velocity metric.

• It is not a package manager. No install, enable, disable, or runtime registration. If that expectation appears in a design doc, kill it there.