Builder Make Command Laravel Package

Getting Started

1. Install and pin. composer require --dev vendor/package:^1.0.9 (the --mixin flag does not exist below 1.0.9, so pin at least that version in composer.json and commit the lock file).
2. Discover the command surface. Run php artisan list and php artisan <command> --help. The --help output is the authoritative reference for the flag set — confirm --mixin is listed before wiring it into scripts, since 1.0.9 is the first release that accepts it.
3. Publish config/stubs if offered. php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" (or --tag=...). Read the published config first; it tells you where generated artifacts land and which paths the command scans.
4. Run once with no flags. Establish a clean baseline of the generated output and commit it. Only then re-run with --mixin and diff, so you can see exactly what the new flag adds rather than mixing baseline noise with feature output.
5. First use case. Regenerate artifacts locally, commit them, and add the same invocation to CI with a git diff --exit-code guard. Add --mixin on the second pass once you have confirmed the extra mixin output is stable and idempotent.

Where to look when something is off, in order: the published config file → the command class in vendor/ (src/Console/) → the generator/service the command delegates to → the generated output directory.

Implementation Patterns

Composer script as the single entry point. Don't let developers memorise flags; expose one script so the flag set evolves in one place:

"scripts": {
    "generate": "@php artisan <command> --mixin",
    "generate:check": "@php artisan <command> --mixin && git diff --exit-code"
}

CI drift check. Run generate:check in the pipeline. Because --mixin changes the emitted file set, an unpinned version in CI is the classic source of "passes locally, fails in CI" — lock the version and run composer install (not update) in CI.

Adopt --mixin as an additive, reviewable change. Land it in its own PR containing only: the version bump, the flag added to the script, and the newly generated mixin output. That diff is the documentation for what the flag does in your codebase.

Keep generated output in version control, config out of it. Commit the artifacts (including the mixin) so consumers of the repo don't need the package installed; keep environment-specific paths in config driven by env vars, not committed overrides.

Layer with existing flags. Check --help for interaction between --mixin and output/namespace/path flags; if the mixin is written to a path derived from an existing --path or namespace option, set both together in the script rather than relying on defaults.

Consume the mixin where it's imported, not where it's generated. Treat the mixin as a shared base applied at the call site. If your toolchain requires registration (a tsconfig include, an autoload entry, a namespace import), add that registration in the same PR as the flag — the command will not do it for you.

Pair with a lint/typecheck step. Generation succeeding says nothing about the output being valid for downstream tooling; run your formatter and typechecker after generate in CI.

Gotchas and Tips

• Flag silently ignored? Almost always a stale lock file or a globally installed older binary shadowing the project one. Verify with composer show vendor/package and php artisan <command> --help in the same shell you run the script from.
• Upgrading within 1.x still needs a diff review. A new flag can change default output paths or overwrite shared files even when you don't pass it. Run the command without --mixin after upgrading and diff against the committed baseline before adopting the flag.
• Idempotency is not guaranteed by the version number. Run the command twice with --mixin and confirm the second run produces a zero-byte diff. If it doesn't, the mixin generator is non-deterministic (timestamps, ordering, hash suffixes) and will break your CI guard — file it and exclude that artifact from the check until fixed.
• Don't run generation in production deploys unless the artifacts are genuinely needed at runtime. It's a build-time/dev-time command; keep it in require-dev and in the build stage.
• Debugging: -v / -vvv for the command, and check the package's log channel if it has one. If output is empty, the scan paths in config are the usual culprit (relative paths resolve from the project root, not the config file).
• Extension points before forking: published stubs, a custom generator/renderer bound in the container, and config-level path/namespace overrides. Publish the stubs and edit them rather than overriding vendor classes — but note that published stubs are frozen at publish time and won't pick up upstream changes from later releases, so re-publish and re-diff on each minor upgrade.
• Mixin naming collisions. If the generated mixin shares a name with an existing trait/mixin in your codebase, generation may overwrite it. Verify the target path in config before the first --mixin run in any repo that already has hand-written mixins.
• Team rollout: the flag is only useful if the script is the documented path. Add the new script name to the README and onboarding docs in the same PR; otherwise half the team keeps invoking the command manually without --mixin and the CI diff fails on their commits.