Laravel Expressive Laravel Package

Getting Started

Install the package and confirm the command surface before writing any code:

composer require wendelladriel/laravel-expressive --dev
php artisan vendor:publish --tag="expressive-config"   # check `php artisan vendor:publish` for the exact tag
php artisan list | grep -i expressive

Two things to inspect first:

1. The config file — it tells you where stubs are resolved from, the namespace/root the generator writes into, and which suffixes/patterns it applies to generated classes. This is the source of truth; don't guess paths.
2. The stubs directory — the generated output is only as good as these templates. Read one stub end-to-end to understand what a generated class actually looks like in your app.

First use case: generate a single class for a feature you're already building.

php artisan make:expressive Foo

Then immediately run the drift check against what you just generated. It should report clean — if it doesn't, your stub or config is misaligned and you want to know that on day one, not after fifty files exist:

php artisan expressive:sync --all   # command name may differ; verify with `php artisan list`

Once a single generate-then-check cycle is green, you're ready to use the v1.2.0 bulk features.

Implementation Patterns

Single-class generation during feature work. Generate as you go, one class at a time, and review the diff before committing. This keeps stub changes visible and stops a stale template from silently propagating across the codebase.

Bulk generation for scaffolding a new domain. v1.2.0 adds bulk Expressive generation — the payoff is bootstrapping a whole slice (model-adjacent classes, actions, concerns) in one pass rather than N invocations. Typical workflow:

# scaffold a batch, then review with git before staging anything
php artisan make:expressive --all        # verify flags via `php artisan help make:expressive`
git status
git diff

Treat bulk output as a starting draft: run it, then edit. The git diff review step is non-negotiable — bulk generation multiplies both correct output and mistakes.

Drift checks in CI. sync-all drift checking is the most valuable new capability, because it turns "our generated classes match our current stubs" into an enforceable invariant. Wire it into CI as a non-mutating gate:

- run: php artisan expressive:sync --all --dry-run   # confirm the dry-run flag exists first

The pattern that matters: CI checks for drift, developers resolve it locally. If CI auto-fixes, drift becomes invisible and stub edits land without review. Run the check in CI, fail the build, and require a human to regenerate and commit.

Stub-first customization. If your team has house conventions (final classes, strict types, custom docblocks), edit the stubs once and regenerate rather than hand-editing output. Hand edits become drift, and drift becomes CI failures you then have to triage individually.

Pair generation with a lint/static-analysis pass. Bulk generation touches many files at once; run Pint and PHPStan/Psalm immediately afterwards so formatting and type issues are fixed in one sweep instead of trickling into unrelated PRs.

Gotchas and Tips

• Pin the version and read the changelog before bumping. v1.2.0 adds functionality but the release notes don't describe flag names, command signatures, or whether bulk generation overwrites existing files. Verify with php artisan help <command> rather than trusting assumptions from a previous version.
• Bulk generation and existing files. The highest-risk unknown in v1.2.0 is overwrite behavior. Before running a bulk command against a real codebase, commit or stash everything — if it overwrites, you want a clean diff to review, not a merge conflict with your uncommitted work.
• Dry-run first, always. Find and use the dry-run/preview flag (if one exists) for bulk operations. If the package doesn't offer one, run bulk generation on a scratch branch the first time and inspect git status before anything else.
• Drift check false positives come from stub edits. As soon as you customize a stub, every previously generated class may register as drifted. Decide deliberately: either regenerate everything in the same PR as the stub change, or scope the check to new files. Don't let a stub tweak silently break CI for the whole team.
• Drift ≠ correctness. sync-all compares generated output against stubs. It will not tell you whether a class is still used, referenced, or semantically correct. Refactors that delete or rename classes need their own cleanup pass.
• Debugging generation failures: check config path resolution and stub existence first, then namespace collisions. A generator that can't find its stub or that targets a namespace not covered by your composer.json autoload rules fails in ways that read like unrelated errors. Run composer dump-autoload after generating into new directories.
• Extension points: stubs and config are the intended customization surface. If you find yourself needing to post-process generated output with a shell script, that's a signal the stub should change instead.
• Keep the package in require-dev. It's a development-time generator; shipping it to production adds weight with no runtime benefit. Make sure CI installs dev dependencies for the drift check to run.
• The dependabot bump (actions/checkout 6→7) is CI hygiene, not a functional change — no action needed beyond confirming your workflows still pass.