Modularous Laravel Package

Getting Started

Modularous (v12.11.1) is a Laravel modular-development suite: it scaffolds self-contained modules (routes, controllers, repositories, models, migrations, and Vue/Vuetify admin screens) rather than letting a single app/ directory sprawl. Start with the scaffold, not the source.

composer require unusualify/modularous
php artisan vendor:publish --tag=modularous-config   # verify the exact tag in your version
php artisan modularous:install                       # or the documented setup command

Where to look first (in this order):

1. config/modularous.php — module paths, namespace mapping, admin panel/auth guard settings.
2. The generated module's Providers/{Module}ServiceProvider.php — it registers routes, migrations, and the admin UI bindings. This is the file that explains "why is my module not loading".
3. The module's Repositories/{Name}Repository.php and its base class — this is where submit() lives (directly or via trait). The v12.11.1 fixes land here, so read the base implementation before you override anything.
4. stubs/ (published) — the fastest way to align generated code with your team's conventions.

First use case: scaffold one CRUD module with a form, then exercise the endpoint twice — once as a browser form POST and once as an axios/postJson request. That single exercise covers routes, repository binding, validation, and the sync-vs-async response branch that v12.11.1 touches. Do this before generating five modules; the response-shape contract will shape everything downstream.

Implementation Patterns

Let submit() be the single write path. The repository/controller submit() method is the orchestration point: validate → persist → respond. Generated admin forms and your own API clients should both hit it. If you find yourself writing a second create/update path for a JSON endpoint, you're duplicating the validation logic the release just hardened — and you'll drift.

Prefer FormRequests over inline validation. v12.11.1 improves "validation handling in the submit method," which almost always means tighter exception-to-response mapping. FormRequests (and $request->validate()) throw ValidationException, which Laravel renders as a 422 with an errors bag. Hand-rolled Validator::make() plus a manual if ($validator->fails()) branch bypasses that and tends to produce a different JSON shape. Pick the exception path and stay on it.

Be explicit about the response contract for async callers. The "async handling" fix implies submit() now discriminates on how the request arrived. Rely on $request->expectsJson()/wantsJson() semantics in your own code rather than sniffing headers manually, and keep one envelope for success:

return $request->expectsJson()
    ? response()->json(['message' => 'Saved', 'data' => $resource], 200)
    : redirect()->route('admin.module.index')->with('success', 'Saved');

Lean on hooks and events, not vendor edits. Model observers, repository before/after-save hooks, and module-level events are the intended extension points. If your module needs post-submit side effects (notifications, related-model sync), register a listener rather than subclassing the repository and re-implementing submit().

Match payload keys to the generated field schema. The Vue/Vuetify forms POST the keys defined by the module's form-field configuration. When you add custom fields, register them in the schema so validation rules and the frontend agree — mismatches surface as silent 422s in the admin UI.

Test both branches explicitly. For every module endpoint, write one postJson() feature test and one post() test. The 12.11.x line changed behaviour in exactly that fork, so a test asserting only the JSON path is not coverage.

Gotchas and Tips

• Re-test overridden submit() methods after upgrading to 12.11.1. If your module subclasses the repository or controller and calls parent::submit(), the changed validation and async branches can alter what your override receives or returns. This is the single highest-risk upgrade surface in this release.
• A redirect returned to an async caller breaks the admin UI. The classic symptom: the form appears to hang or throws in the axios response interceptor because an HTML 302 came back where JSON was expected. Check that your request actually sends Accept: application/json (axios does by default; a hand-built fetch may not).
• Multipart vs JSON divergence. File-upload forms send multipart/form-data, which changes how validation errors and partial failures surface. Test uploads separately from text-only forms rather than assuming the async path is uniform.
• config:clear after touching config/modularous.php. Config and module-registration caching will otherwise mask changes and make it look like a provider isn't registered. Same for route caching when a new module's routes don't appear.
• Debug the request shape first. When a submit fails ambiguously, log $request->expectsJson(), the Accept header, and $request->all() before the validation call. Most "validation is broken" reports are payload-key or content-type mismatches, not rule problems.
• Don't edit published stubs and vendor code in tandem. Publish stubs, customise them, and regenerate — otherwise the next module you scaffold silently reverts your conventions.
• Pin the patch version in composer.json if the admin UI is mission-critical. 12.11.1 is a patch release in a line that is actively changing submit behaviour; locking to 12.11.* and reviewing each bump is cheaper than debugging a mid-sprint response-shape change.
• Confirm the changelog against your install. The release notes for 12.11.1 name two commits (77b0416, f4bcd50) touching the same method. Diff them against your vendor copy to see precisely which branch changed before assuming your customisations are safe.