Laravel Api Scaffold Laravel Package

Getting Started

Upgrade the package and refresh published config before generating anything new:

composer require caminodeldev/laravel-api-scaffold:^0.4.0 -W
php artisan vendor:publish --tag=api-scaffold-config --force
php artisan config:clear && php artisan cache:clear

Then look at the new models block in config/api-scaffold.php first — it is the only thing that changed in your day-to-day workflow:

'models' => [
    'generate_relationships' => true,
    'generate_phpdoc' => true,
    'phpdoc_decimal_type' => 'string',
],

First use case: you have (or are about to create) a pair of related tables, e.g. scaffold_clientes and scaffold_transacciones.scaffold_cliente_id -> scaffold_clientes.id. Regenerate both models:

php artisan scaffold:model scaffold_transacciones --connection=mysql --model=ScaffoldTransaccion --force
php artisan scaffold:model scaffold_clientes --connection=mysql --model=ScaffoldCliente --force

You should now get belongsTo on the child, hasMany on the parent, and a PHPDoc block on both. If you get models with no relationships, check config is published/cached-cleared before debugging anything else.

Implementation Patterns

Treat model generation as a build step, not a one-off. The valuable workflow is: migrate schema → regenerate models → regenerate API. Keep the exact commands in a Makefile/sail alias/composer script so --force regeneration is routine and the PHPDoc + relationships never drift from the schema.

php artisan scaffold:api scaffold_transacciones \
  --connection=mysql --model=ScaffoldTransaccion \
  --route-resource=transacciones --crud --with-delete --force

Generation order matters for review, not for output. Relationships and PHPDoc are computed from live FK metadata, so generate parents and children in the same run/session; regenerating only the child leaves the parent's inverse hasMany stale.

Split the flags for legacy codebases. On a project with hand-edited models, enable generate_phpdoc first (pure documentation, zero runtime impact), verify the diff, then flip generate_relationships on. Two smaller diffs are far easier to review than one.

Pin phpdoc_decimal_type per project. Keep the string default if you generate decimal:2 casts — it matches what Eloquent actually returns. Switch to float only if you deliberately cast decimals to float and your static analysis (PHPStan/Larastan, IDE) is complaining about string math.

Use relationships immediately in generated tests. The release's own validation drives belongsTo/hasMany at runtime through generated feature tests. Mirror that: after regeneration, assert $transaccion->scaffoldCliente and $cliente->scaffoldTransacciones resolve — that catches mismatched connection/table-prefix setups that php -l never will.

Eager-load in the layer above the generator. Relationships are generated on models only; generated controllers/queries are not automatically eager-loaded. Add with('scaffoldCliente') in your resource/controller layer to avoid N+1 on list endpoints.

Multi-connection apps: always pass --connection= explicitly, and generate per connection. FK introspection runs against the connection you name (MySQL/MariaDB and PostgreSQL supported), so a model generated against the wrong connection silently loses its relationships.

Gotchas and Tips

• --force overwrites hand-written code. Any custom accessors, scopes, or manually added relationships in generated models are lost. Keep customisations in traits or subclasses, or stop using the generator for that model.
• Regeneration is mandatory after schema changes. PHPDoc and relations are snapshots; a new FK added later will not appear until you regenerate both sides.
• Only belongsTo/hasMany exist. No belongsToMany, no polymorphic relations (confirmed in the release's compatibility notes). Pivot tables and morphTo must be written by hand — and hand-written ones survive only if you don't --force that model.
• Inverse relations depend on discoverable FK metadata. Inverse references are generated "where applicable"; composite foreign keys, FKs to non-primary columns, and cross-database/cross-schema references are the usual suspects for a missing hasMany. Verify with a runtime check rather than assuming.
• Method naming is derived from table names. scaffold_transacciones → scaffoldTransacciones, and the belongsTo side becomes scaffoldCliente. Irreversible/irregular plurals, table prefixes, and self-referencing FKs (parent_id) can produce awkward or colliding names — rename in a trait/subclass if it matters.
• Decimal PHPDoc is string, deliberately. Don't "fix" it to float; decimal:2 casts return strings in Laravel. If your code does arithmetic, cast at the boundary.
• PHPStan/Larastan will now see the models differently. New @property Collection<int, X> and relationship properties can shift baseline errors. Re-run static analysis after regenerating.
• Config caching bites. vendor:publish ... --force followed by a stale config:cache (or an un-reloaded Octane worker) is the #1 cause of "the new models block does nothing". Run php artisan config:clear then php artisan optimize:clear && php artisan octane:reload on Octane/Swoole.
• --force on scaffold:api regenerates routes, resources, controllers and tests — verify route names/resource slugs in the diff, especially if you had customised generated tests.
• Extension point: the models config block is the supported toggle surface. If you need behaviour it doesn't expose (custom namespace for relationship imports, alternative PHPDoc templates), prefer post-generation formatting via your own Artisan command or a Pint/stub step over editing vendor files.
• Debugging checklist for "no relationships generated": config published? config cache cleared? generate_relationships true? correct --connection? FK actually defined in the DB (not just in a migration)? both sides regenerated?