Laravel Modules Laravel Package

Getting Started

Install the package, publish its config, and you are ready to create your first module:

composer require sinemacula/laravel-modules
php artisan vendor:publish --tag=modules-config   # config/modules.php
php artisan module:make Blog                      # scaffold a module

Look at config/modules.php first — it defines where modules live (the module base path), the manifest/cache behaviour, and the naming rules applied to module names. Then look at a generated module skeleton: it shows you the conventions the package expects for service providers, routes, migrations, models, and resources. That skeleton is the contract; deviate from it and the convention-based resolution (including the new factory resolution) stops working.

First practical use case: scaffold one module, add a model + migration, and hit it through a route registered in that module's route file. Once that round-trip works, register a second module and confirm they are isolated from each other and from the host app.

Implementation Patterns

Module-as-bounded-context. Keep each module self-contained: Models/, Http/Controllers/, routes/, database/migrations/, resources/. Register bindings and event listeners from the module's own service provider rather than from AppServiceProvider; that is what makes modules removable without leaving dangling references.

Factories by convention (new in 1.4.0). Module models can now resolve their factory without an explicit newFactory(). Follow the package's namespace convention for the model and its factory and Model::factory() just works. This is worth adopting across an existing codebase: it removes boilerplate from every module model, but only if you are consistent — a model whose factory lives under a non-standard namespace still needs an explicit newFactory(). Audit your models before deleting existing overrides; override-beats-convention is the safe assumption, but do not assume a misnamed factory will be found.

Discarding the module base path (new in 1.4.0). Previously every module path was prefixed by the configured base directory. If you want modules to live at the application root, or to mount a module at an arbitrary path (a package-like layout, or a module sourced from a different root entirely), use the new option instead of fighting the config with ../ segments. Treat this as an install-time decision — changing it later means changing every path, published asset, and migration reference at once.

Manifest and cache in the deploy pipeline. The module manifest is a build artefact. Generate it as part of composer install/deploy, and clear it on rollback. In 1.4.0 the manifest is only consulted "while it is usable", so a stale or partially-written manifest degrades to scanning rather than silently serving wrong module data — good for correctness, but it means a broken manifest can show up as unexpectedly slow boot rather than an error. Watch boot time in CI as a canary.

Surfacing naming and path problems early. Two new reports are worth wiring into your logging/monitoring:

• module name rewritten — the package tells you when it had to normalise a name. In practice this means a scaffolded or hand-added module does not match the name you think it has.
• resource path naming a module with nothing to serve — a route or resource points at a module that exists but has no matching resource. This is almost always a typo or a leftover reference.

Both are reported rather than thrown, so they will be invisible unless you are reading logs. Run a fresh boot in CI with your log channel asserted, or add an assertion in a smoke test.

Cache write failures. 1.4.0 reports rather than crashes when the module cache cannot be written. That is friendlier in read-only filesystems and container cold starts, but it means a permissions problem now presents as performance degradation. If module boot suddenly gets noticeably slower in one environment, check write permissions on the cache location before anything else.

Gotchas and Tips

• Base path changes ripple. Discarding the module base path alters every resolved path: asset publishing, view namespaces, migration paths, and any hardcoded base_path('modules/...') in your own code. Grep for the base path string before flipping the switch, and re-run vendor:publish for module assets afterwards.

• Paths are canonicalised now. 1.4.0 canonicalises the application base path, so comparisons behave consistently — but any code of yours that compares module paths as raw strings (trailing slash, symlinked release directories, storage symlinks in zero-downtime deploys) may now disagree with what the package reports. Compare resolved/canonical paths, not literals.

• Regenerated stubs mean drift. The 1.4.0 stub fix makes generated modules standards-compliant. Modules scaffolded before this release will differ from newly generated ones. Do not bulk-regenerate; diff one new stub against an existing module and backport the relevant changes by hand.

• Factory convention needs the whole namespace to line up. If Model::factory() returns the wrong factory or throws, check the module namespace and the factory's $model property before assuming the convention is broken. Explicit newFactory() still wins and is the correct escape hatch.

• The manifest is a cache, not a source of truth. Never edit it, never commit it blindly across environments, and always regenerate on deploy. If modules "disappear" after a deploy, clear the manifest and let the package rescan before debugging anything else.

• Reports vs exceptions. The 1.4.0 changes deliberately soften several failure modes (rewritten names, empty resource paths, cache write failures, unusable manifests). This is the right behaviour for production but makes local development quieter than it should be. Set your module log channel to debug locally so these reports are visible while you work.

• Extension points. The module service provider is the intended seam for registering bindings, migrations, routes, and commands. Keep the host app's providers free of module-specific knowledge — that is what makes the "discard the base path" and "swap a module out" workflows actually viable.