Laravel Api Scaffold Laravel Package

Technical Evaluation

Architecture fit: laravel-api-scaffold remains a code-generation tool layered on standard Laravel conventions (Artisan commands, Eloquent models, migrations introspection). v0.4.0 does not introduce a runtime dependency or middleware/extension surface — the generated models use vanilla belongsTo/hasMany and standard decimal:2 casts. That keeps architectural coupling low: the package can be adopted by a single team on a single bounded context without touching application bootstrapping.

What changed that matters to a TPM:

• Foreign-key introspection now runs against both MySQL/MariaDB and PostgreSQL (local column, referenced table, referenced column, constraint name, inverse references).
• Generated models contain belongsTo (child) and hasMany (parent) relationships plus PHPDoc @property blocks for columns and relations.
• New published models config block with three knobs: generate_relationships, generate_phpdoc, phpdoc_decimal_type (default string, aligning PHPDoc with Laravel's decimal:N cast returning strings).
• Both scaffold:model and scaffold:api emit the enriched output; imports (BelongsTo, HasMany, Collection, Carbon) are emitted only when needed.

Integration feasibility: High for greenfield or convention-following schemas. The release is opt-in by configuration, and — critically — existing generated files are unchanged until someone re-runs the generator. Upgrade risk is therefore near zero at runtime and concentrated entirely in the regeneration step. Both consumer validations (MySQL and PostgreSQL) exercised the full path: publish config → scaffold:model → scaffold:api → php -l → generated feature tests pass → runtime relationship calls verified. That is the right evidence set for a scaffolding tool, because it demonstrates the artifact is syntactically and behaviourally sound in a real consumer app, not just inside the package test suite.

Technical risk:

1. --force overwrite of hand-edited models (highest). The documented regeneration commands use --force. Any consumer that has added custom accessors, scopes, casts, or business logic to a generated model will lose them. This is the single most likely production incident from this release.
2. Output drift / one-way generation. PHPDoc and relationships are snapshots at generation time. Schema changes made later by migrations will silently desynchronise models unless regeneration is part of the routine. A stale @property block is worse than none for static analysis (PHPStan/Psalm).
3. Naming and collision semantics are inferred from table/column names. Spanish plural table names produce methods like scaffoldTransacciones. Collisions with existing methods (user(), items(), model name casing) or PHP-reserved identifiers are not documented as guarded against.
4. Unsupported relationship classes are explicit but incomplete: no belongsToMany, no polymorphic relations. Schemas with pivot tables or morph columns will get a partial model graph that looks complete, which is a subtle correctness trap for reviewers.
5. Inverse hasMany fan-out. Every referencing table yields a hasMany on the parent. Hub tables with many inbound FKs will produce large models and larger PHPDoc blocks; no filtering/allow-list is documented.
6. Pre-1.0 version semantics. ^0.4.0 gives no API stability guarantee; generated output format is a de facto public contract that the package may still change in 0.5.x.
7. Config republish uses --force, which overwrites any consumer customisations to the package config file.

Key questions:

• What is the supported Laravel and PHP version matrix, and is it verified in CI or only asserted? (Not stated in the notes.)
• Can regeneration be scoped to a directory/namespace so it can be trialled without --force over existing models?
• Is there a --no-relationships / --no-phpdoc per-invocation flag, or is suppression only via the published config file (which is global)?
• How are composite foreign keys, self-referencing FKs, and circular FKs handled? Are they skipped, emitted, or do they fail generation?
• What DB user privileges are required for FK metadata reads on each driver (e.g. information_schema visibility), and what happens when introspection returns nothing — silent success or error?
• Are relationship method names singularised/pluralised via Laravel's inflector, and can naming be overridden per table?
• Does the package's own suite (58 tests / 274 assertions) run against both MySQL and PostgreSQL, or is cross-driver coverage manual only?

Integration Approach

Stack fit: Native Laravel/PHP. Fits any LEMP/LAPP or managed-DB estate where Eloquent is the data layer and Artisan is the operational interface. No additional infrastructure, queue, or service dependency is introduced. Works with Octane/Swoole — the notes explicitly cover optimize:clear + octane:reload, which is the signal that the package has been tested against long-lived worker runtimes rather than only FPM.

Migration path (recommended sequencing):

1. Pin the version, do not float. composer require caminodeldev/laravel-api-scaffold:^0.4.0 -W in a feature branch. Given 0.x semantics, consider an exact pin (0.4.0) until v1.0.
2. Publish config additively first. Publish to a scratch copy and diff against the existing published config before running --force. Confirm the new models block lands with the intended defaults (generate_relationships: true, generate_phpdoc: true, phpdoc_decimal_type: string).
3. Trial generation in a non-production namespace/directory on 1–2 tables that have FKs (ideally a child and its parent) and inspect the diff. Verify: relationship method names read naturally, PHPDoc matches actual columns and nullability, imports are present and minimal.
4. Regenerate only models you are willing to overwrite. For models with bespoke logic, either hand-apply the relationship methods and PHPDoc, or extract customisations into traits/Scopes before running --force.
5. Clear caches and reload workers (config:clear, cache:clear, optimize:clear, octane:reload) as documented — stale config or opcache is the most common cause of "the config option did nothing".
6. Expand to scaffold:api only after scaffold:model output is accepted, since scaffold:api regenerates a larger surface (routes, resources, controllers, tests) with the same --force behaviour.
7. Enable in CI as a lint gate: regenerate on a scratch branch and assert a clean diff, so schema drift is caught at PR time rather than in production.

Compatibility:

• Source-compatible: no changes to existing generated files, no changes to command signatures, no deprecations announced.
• Output-incompatible in one direction only: regenerated models differ from prior output. Any repo that has committed generated models and treats them as reviewed artifacts must plan a deliberate diff review.
• Config-file incompatible: the new models block requires a republish to be present; teams that skip republishing simply get no relationships/PHPDoc (feature-off by absence), which is a safe fallback but should be documented internally so silence isn't mistaken for a bug.
• Explicitly out of scope: belongsToMany, polymorphic relations. Do not market this internally as "full relationship generation".

Rollback: Trivially easy — revert the regenerated files (they are source artifacts) and drop the package version. No migrations, no schema changes, no data implications.

Operational Impact

Maintenance: Low ongoing cost, moderate one-off cost. The package itself is a dev dependency whose blast radius is limited to generated files. The real maintenance burden shifts to process: someone must own the decision of when models are regenerated versus hand-edited, and the repo must have a diff-review discipline for generated artifacts. The PHPDoc blocks are the highest-churn element — they will rot silently if schema changes are frequent and regeneration is ad hoc.

Support: Small. Failure surface is generation-time (introspection, naming, file writes) rather than runtime. Support requests will cluster into three predictable categories: overwritten custom code, relationships not appearing (config not republished, wrong --connection, --force not passed), and odd relationship names on non-conventional schemas. Team ramp-up is very low — anyone who can run Artisan commands can use it; the learning is in the guardrails, not the tool.

Scaling:

• Schema scale: introspection is per-invocation over the target connection. On schemas with hundreds of tables, expect each run to make multiple metadata queries; generation time will grow roughly linearly. Fine for incremental use, potentially slow for whole-schema regeneration — worth measuring before adopting as a CI-wide gate on a large estate.
• Codebase scale: the inverse hasMany fan-out means a small number of hub tables accumulate very large models and PHPDoc. Consider disabling generate_phpdoc selectively, or accepting churn in those files.
• Runtime scale: zero. Generated code is plain Eloquent; there is no new query pattern, no lazy-loading change introduced by the package beyond what a developer would have written by hand. Note that adding relationships does make it easier for developers to trigger N+1 queries via lazy loading — a code-review concern, not a package defect.

Failure modes and mitigations:

Recommendation: Adopt. The release is additive, opt-in, and validated end-to-end on both supported drivers, with a trivially reversible failure mode. Gate adoption on two things before rolling out broadly: (1) an inventory of foreign-key topology to identify composite/circular/pivot cases the release does not cover, and (2) a documented regeneration policy that protects hand-edited models from --force. Treat generated models as reviewed artifacts with a CI drift check, and pin the version exactly until v1.0 given pre-1.0 semantics.