Laravel Stubs Laravel Package

Technical Evaluation

Architecture fit. This package sits entirely in the developer-enablement layer, not the application architecture. It ships stub templates that Artisan's make:* commands render — models, controllers, migrations, jobs, events, policies, form requests. There is no service provider in the runtime path doing anything customer-visible, no container binding, no route registration, no schema effect, no deploy artifact. For a TPM that means it belongs in the same governance bucket as Pint, Larastan, and Rector: configuration-as-code that shapes how the team writes software, not what the software does. Fit is high conditional on a written convention existing. If the team has an agreed standard (declare(strict_types=1), final-by-default, typed properties, promoted constructors, defined namespaces), the stubs are a head start that makes generated code pass CI on the first run. If the standard is unstated or contested, this package becomes a proxy for a debate that then plays out in code review, which is the worst possible venue.

Integration feasibility. Mechanically trivial: a dev-only Composer require, one Artisan publish command, and the stub files land in the project. The genuine cost is organizational — one standards-owner review, one alignment conversation, one documentation update. Size this in hours of engineering plus a meeting. Anyone proposing a sprint for it is over-scoping; anyone proposing zero time is under-scoping the decision step.

Technical risk. Low on runtime, moderate on process, with one dependency risk to record explicitly:

• Silent stub drift. Stub filenames track Laravel's skeleton and change across majors. A stale or misnamed stub is not an error — the framework silently falls back to the default template. The failure mode is "generated code quietly stopped matching our standard," which is a detection problem, not a build problem.
• Convention lock-in. final classes and strict types can break mocking strategies and legacy untyped code paths. This often surfaces as test failures weeks after adoption, so a canary service and a one-commit rollback plan are prerequisites, not niceties.
• Adoption signals. The repository shows zero stars, zero dependents, and a single maintainer. That is not evidence of poor code — the author is a recognized Laravel contributor — but it is evidence that no one else is applying upgrade pressure. Plan for the maintainer to walk away and ensure nothing in our process depends on them.

Key questions to close before a go decision.

1. Which Laravel and PHP versions are the stubs written against, and is there CI tracking the framework skeleton across majors?
2. Does the package only ship files, or does it register a provider that overrides stub resolution? File-only means we can vendor and drop it; provider-based means an upgrade-time dependency we must carry.
3. What is the license, and does it permit copying the stub files into our own repositories?
4. Do the generated artifacts pass our existing Pint, Larastan, and Rector configurations without edits?
5. Does the authored opinion match our written standard, or would we be codifying someone else's preferences by accident?
6. What is the release cadence over the last 12 months, and is there a tagged release per Laravel major?

Integration Approach

Stack fit. Orthogonal to everything else in the stack. It is indifferent to database, queue driver, frontend, hosting model, and team topology, and it composes cleanly with a "generated code is already compliant" workflow. The one real collision risk is a second stub-publishing package in the same repository — resolution order and publish conflicts produce "why did my model generate wrong" incidents that are slow and expensive to diagnose, and they erode trust in the scaffolder itself.

Migration path — harvest, do not depend. Frame this as a decision gate, not an engineering preference:

1. Spike. On a branch, on one greenfield service, install as a dev dependency, publish the stubs, and generate a representative sample: model, controller, form request, policy, job, feature test, migration.
2. Diff as the deliverable. Compare generated output against framework defaults and against our hand-written conventions. That diff is what goes to standards review — it converts an abstract "should we standardize scaffolding" question into a concrete, reviewable proposal.
3. Decide. If the opinions match: vendor the stubs/ directory as first-class source, commit it, and remove the package from composer.json. If they do not: lift the good parts into an internal stub set and move on. Either way the dependency does not persist.
4. Codify. Document the conventions in CONTRIBUTING.md and add a CI assertion that a freshly generated artifact passes lint and static analysis. Without this step, adoption decays as soon as attention moves elsewhere.

The stakeholder framing: this converts a zero-star dependency into roughly fifteen reviewed template files we own outright. The value is in the opinion, not the package.

Compatibility. Two hard constraints — Laravel major and PHP minor — and the Laravel one fails silently. Stub filenames must match what that release's make commands expect. Add a line to the standard Laravel upgrade checklist: re-verify vendored stubs against the new skeleton, generate one artifact per stub type, diff. It is a ten-minute recurring task that prevents a year of quiet divergence. Pin the PHP version alongside it; promoted-constructor and readonly syntax in stubs need a minimum PHP minor that should be stated in the README.

Sequencing and schedule risk. Standards owner reviews contents (half a day) → branch spike and diff (half a day) → team review of proposed conventions (the long pole: budget a decision owner and a date, not a sprint) → vendor, drop the dependency, document (one day) → optional CI assertion. Engineering effort is small; essentially all schedule risk is concentrated in the review step. The TPM's job is to ensure that step has a named decision-maker, otherwise the spike rots on a branch and the effort is wasted.

Rollout scope. Greenfield services, new bounded contexts, and the shared starter template only. Do not retrofit into existing repositories mid-sprint — the diff is noise there, conventions are already de facto settled, and the retrofit risk outweighs the benefit.

Operational Impact

Maintenance. Near zero once vendored: inert text files that change only when we deliberately change them. If kept as a live dependency instead, maintenance becomes a per-major audit plus dependency-bot noise, for a package that provides no runtime capability. Vendoring is strictly better on this axis, so "keep the dependency" should be the option requiring justification.

Support and ownership. No commercial support, no SLA, single maintainer, no observable consumer base. Internal ownership must be assigned by name — realistically the same person or guild that owns Pint/Larastan configuration and the written code standard. The failure mode of unowned stubs is not breakage; it is slow divergence, where half the codebase is generated one way and half another and nobody notices for a year.

Scaling. Scales linearly and cheaply: vendored files replicate with the repository, cost nothing at build or runtime, and impose no per-service overhead. The characteristic that does not scale is judgment — a single stub set across many teams requires the standard to be genuinely shared, or each team will fork its own stubs and the consistency benefit evaporates.

Failure modes to monitor. (a) Misnamed or removed stub → silent fallback to framework defaults; detect with a CI job that generates one artifact per stub type and diffs it against a committed expectation. (b) Framework major upgrade changes stub shape → generated code diverges from the new skeleton; detect at upgrade checklist time, not in production. (c) Second stub-publisher in the repo → resolution-order bugs; detect by convention, one scaffolder per repository. (d) Stubs encoding opinions incompatible with test tooling → surface as late test failures; detect with a canary service before fleet rollout. None of these are customer-visible, which is precisely why they need automated detection — nobody will notice them manually.

Ramp-up. Very low for engineers who already know Artisan: the mental model is "the templates are ours now," and reading fifteen files takes under an hour. The ramp-up cost sits with new hires who will follow tutorials that assume stock Laravel output — so the README and CONTRIBUTING.md must state explicitly why our generated code differs from the defaults, or newcomers will "fix" it back to the framework shape. Budget a paragraph of documentation, not a training session.