Weave Code
Laravel Modules Laravel Package
sinemacula/laravel-modules
A modular structuring package for Laravel applications, providing a foundation for organizing code into self-contained modules. Useful for teams building maintainable, scalable apps with clear separation of concerns.
A lightweight, convention-driven modular architecture package for Laravel - auto-discovers modules as directories with zero manifests, zero boilerplate, and nothing new to learn
Frequently asked questions about Laravel Modules
- How do I install sinemacula/laravel-modules in a Laravel application?
- Install it with Composer using composer require sinemacula/laravel-modules. It targets Laravel's standard service-provider and package-discovery model, so it drops into a normal Laravel app without bootstrap surgery or additional required dependencies. After installing, you agree on module boundaries and naming conventions and start creating module directories.
- Does every module need a manifest file with this package?
- No. The package is convention-driven and auto-discovers modules as directories, so there are zero manifests and zero boilerplate to start. As of v1.4.0, manifest handling was also made defensive: a module manifest is only used while it is usable, so a stale or partially written manifest is ignored rather than consumed. That matters if you deploy concurrently or clear caches while a deploy is in flight.
- Which Laravel and PHP versions does sinemacula/laravel-modules support?
- The package is built for Laravel applications and follows Laravel's package-discovery and service-provider conventions. Version 1.4.0 is a minor release with no new required dependencies and no configuration schema changes called out. Check the repository's composer.json constraints for the exact Laravel and PHP version ranges before adopting it in a legacy codebase.
- How does module auto-discovery work and where should module directories live?
- Modules are discovered as directories, each getting its own namespace plus its own service providers, routes, migrations, resources, and model factories. There is no registration step or per-module config file to maintain, which is what keeps the boilerplate at zero. v1.4.0 also added path canonicalisation, which is worth verifying if you run on Windows agents or deploy to symlinked release directories such as Capistrano or Deployer current symlinks.
- How are module routes, migrations and service providers registered?
- Each module carries its own service providers, routes, migrations, and resources, and the package wires them up automatically through Laravel's normal provider and discovery model. You do not write a central registry listing every module. If a module has no resource paths, v1.4.0 now reports that rather than silently skipping it, which helps when debugging a module that appears not to load.
- Does the package resolve model factories by convention?
- Yes, v1.4.0 added factory-by-convention resolution so modules can resolve Database\Factories classes without explicit registration. In practice it is opt-in, since you only benefit if you follow conventional naming. Be aware it can change which factory a test picks up if a module factory name collides with a conventionally resolved one, so run your suite with parallel testing disabled first to expose any resolution ordering effects.
- What is the discardable module base path feature for?
- It lets you serve modules from a base path that should not appear in generated URLs, asset paths, or resource resolution. It is a configuration concern rather than a code change, so it needs a config review before you enable it. Confirm with the maintainer whether the semantics cover URL generation only or also filesystem resolution, since that affects asset and resource lookups.
- Is upgrading to v1.4.0 safe and are there breaking changes?
- It is a minor SemVer bump with no BREAKING CHANGE footers, and the release is additive or defensive rather than a feature expansion. The residual risk is behavioural: manifest handling, path canonicalisation, and cache write failure handling all changed. Upgrade in a feature branch, run the full test suite with parallel testing disabled first, and diff your generated module output if you re-run the generators.
- How does it compare to nwidart/laravel-modules?
- sinemacula/laravel-modules is deliberately lightweight and convention-driven: modules are discovered as plain directories with no manifests and no boilerplate, and there is nothing new to learn beyond Laravel conventions. That makes it a good fit for teams that want clear separation of concerns without a heavy module management layer. It is not a drop-in replacement for packages with their own module CLI and registry, so evaluate it against how much structure your teams actually need.
- How should I test modules and handle cache failures in production?
- Run the full suite with parallel testing disabled first so any factory-resolution ordering effects from convention-based factory lookup are visible. In v1.4.0, cache write failures are reported instead of throwing, so make sure that reporting channel actually reaches your logs and alerting rather than being swallowed. Also test your deploy pipeline's behaviour when a manifest exists but is mid-write, since the package now ignores unusable manifests rather than consuming them.
Weaver
How can I help you explore Laravel packages today?