Structuremanager Laravel Package

Getting Started

The Structure Manager is a CLI companion to the Laravel Enso core (laravel-enso/enso). It is not useful standalone — install and configure Enso first, then add this package so its Artisan commands can scaffold the pieces Enso expects (models, migrations, routes, menus, permissions, etc.).

composer require laravel-enso/structuremanager --dev

No manual provider registration is required on Laravel versions with package auto-discovery; on older versions add the package service provider to config/app.php. After install, confirm what got registered before doing anything else:

php artisan list | grep -i structure

That command list is the fastest way to understand the package — it tells you exactly which generators your installed version exposes. Command names have shifted between Enso releases, so treat the names below as the shape of the workflow rather than a guaranteed literal API.

A typical first use case: you are adding a new entity ("Invoice") to an Enso app and need all the plumbing Enso assumes exists — a model, a migration, a table, a controller and request, an API route, a menu entry, and the CRUD permissions that guard it. Rather than writing those by hand and hoping they match Enso's conventions, you generate them:

php artisan structure:model Invoice
php artisan structure:migration invoices
php artisan structure:controller Invoice
php artisan structure:route Invoice
php artisan structure:menu Invoice
php artisan structure:permission Invoice

Then run the migration and reseed:

php artisan migrate
php artisan db:seed --class=MenuSeeder   # or Enso's own seeder

The generated files are ordinary PHP — review them, adjust namespaces, and commit. That review step is where most of the value is; the generator gets you 80% of the boilerplate and the Enso conventions right.

Implementation Patterns

Scaffold in dependency order. Model → migration → factory/seeder → controller/request → route → menu → permission. Menu and permission generation frequently depend on the model/table already existing (they may reference the model class or inspect columns), so running them out of order produces failures or half-populated records.

Treat it as a development-time tool, not a runtime dependency. Everything it produces is plain application code. Once generated, the package can be removed from composer.json without breaking the app — useful if you want a lean production install.

Generate, then diff, then commit. Run one command at a time in a clean working tree. Because generators write files, git diff is your review surface. This is especially important for anything that appends rather than creates — route files and menu seeders are the usual suspects.

Use it for Enso module/package development. If you build reusable Enso modules, the structure commands give you the correct Models/, Http/Controllers/, Routes/, and permission naming so the module drops into any Enso host app without manual wiring. This is arguably the package's strongest use case.

Keep permissions and menus in sync deliberately. Enso's RBAC depends on permission records existing and matching route/controller names. When you rename a controller or route, re-run the permission generator rather than editing rows by hand — hand edits drift from the code.

Customize stubs rather than post-editing every file. Most Enso generators read from stub templates. Publish them once, edit the published stubs to match your house style (strict types, final classes, custom docblocks), and every subsequent generation inherits your conventions. Look for a vendor:publish tag like structure-stubs or a config key pointing at a stubs path.

Wire into your onboarding docs. For teams, a short "how to add a new entity" checklist built around these commands is more valuable than the README — it encodes the order and the follow-up steps (migrate, seed, assign permissions to roles) that the commands intentionally leave out.

Gotchas and Tips

• Version lockstep with Enso core. This package tracks laravel-enso/enso closely. Upgrading one without the other is the most common source of "command not found" or service-provider errors. Pin both to compatible majors and upgrade together.
• Generators overwrite. Assume any generator will clobber an existing file without prompting unless you've verified otherwise for your version. Commit before running, and never run them against uncommitted work.
• Database-dependent commands fail early. Menu and permission generators touch the DB. If you see "table not found" or empty output, check that migrations have run and the relevant Enso tables exist and are seeded.
• Duplicate rows on re-run. Menu and permission generation often inserts rather than upserts, so re-running can create duplicate menu items or permission entries. Check the tables (menus, permissions) after re-running; truncate-and-reseed is often cleaner than fighting duplicates.
• Appended routes duplicate too. Route generation may append to an existing routes file. Re-running produces duplicate route definitions that silently shadow each other. Search the file after generating.
• Naming conventions are strict. Enso expects singular StudlyCase model names and plural snake_case tables. Acronyms (APIKey, OAuthToken) are a frequent source of wrong class names or wrong table guesses — verify both after generation.
• Namespace and path come from config. If generated files land in the wrong directory or namespace, don't edit output files one by one — fix the config first, delete the bad output, and regenerate. Otherwise every future run repeats the mistake.
• Debugging a generator. Run with -vvv first; if that's not enough, read the command class under vendor/laravel-enso/structuremanager/src/Console/Commands/ — the source is small and directly shows which stubs and config keys it reads. This is faster than guessing at flags.
• Extension points. The practical customization surfaces are (1) published stubs, (2) the package's config file for namespaces/paths, and (3) the container — if the generator resolves a class from the container you can bind your own implementation. There is no plugin system beyond that; if you need different output, custom stubs are the intended answer.
• Don't confuse it with Enso's migration/upgrade tooling. Structure Manager creates new application structure. It does not migrate an existing app between Enso versions — that's a separate concern, and mixing the two workflows leads to broken installs.