Module Manager Laravel Package

Technical Evaluation

What the package actually is. Despite the name, nasirkhan/module-manager is not a general-purpose modularisation library. It is the module runtime plus a content bundle (Post, Category, Tag, Menu, ActivityLog) for one specific application skeleton, Laravel Starter. The CLI surface (module:status, module:dependencies, module:publish, module:build, module:enable/disable, module:remove) and the module.json manifest (name, alias, priority, requires) define an opinionated HMVC convention: modules live in Modules/, are discovered by a service provider, loaded in priority order, and gated by requires.

Architecture fit.

• Good fit: greenfield Laravel apps already structured around a Modules/ directory with PSR-4 mapping for Modules\. The manifest-driven dependency resolution and priority ordering are the genuinely valuable parts — they solve a real coordination problem in multi-team Laravel codebases.
• Poor fit: existing monoliths with app/-centric structure, or teams already on nwidart/laravel-modules. The two occupy the same namespace of concerns with incompatible manifests and discovery mechanisms; running both is not a defensible plan.
• Actively constraining: the package bundles domain modules (blog posts, tags, menus, media handling via intervention/image-laravel, activity logging via spatie/laravel-activitylog). You cannot adopt the manager without also inheriting those transitive dependencies, whether or not you want the Post module. v7.0.0 made this worse by promoting both to direct package dependencies — a breaking change that required downstream composer.json edits.

Integration feasibility. Mechanically trivial on paper: composer require, php artisan module:status, run migrations. Requirements are PHP ^8.3 and Laravel ^12 || ^13.0, which means the package tracks the two most recent Laravel majors and you inherit its upgrade cadence — if Laravel 14 lands before the maintainer publishes, you are blocked at the framework level, not the package level. The publish model (module:publish) rewrites namespaces from Nasirkhan\ModuleManager\Modules\{Module}\... to Modules\{Module}\..., followed by composer dump-autoload and config:clear. That is a code-generation step that produces a permanent fork in your repository; module:diff exists precisely because drift is expected.

Technical risk.

• Bus factor 1. Single maintainer (nasirkhan), 10 GitHub stars, 0 dependents on Packagist. There is no signal of third-party production usage, so there is no proxy for battle-testing beyond the maintainer's own starter.
• Ecosystem isolation. Zero dependents means no community patches, no Stack Overflow corpus, and no incentive for the maintainer to preserve interfaces your fork relies on. Every upgrade is effectively a re-vendoring exercise.
• Bespoke migration tracking. MigrationTracker records baselines (trackModuleMigrations) and diffs against them (getNewMigrationsSinceLastCheck). This is a second source of truth alongside Laravel's migrations table, and the README documents the detection workflow but not the rollback or recovery workflow. That is the highest-severity unknown.
• Namespace rewriting is mechanical. Any hand-written extension you add before publishing will not survive a re-publish; any customisation you make after publishing will not be visible to module:diff as a conflict.
• Version/date anomaly. The latest release is dated 2026-11-01 while the package scores 34.39 and shows low adoption — the release feed and the scoring snapshot are inconsistent. Verify the artifact provenance before treating release recency as a maturity signal.

Key questions to put to the maintainer (or resolve ourselves).

1. Where does migration baseline state live, and what is the recovery path when a published migration is edited or a module is disabled mid-upgrade?
2. Is dependency resolution topological, and does a cycle in requires fail loudly at boot or silently mis-order?
3. What is the tested-behaviour matrix — does the CI workflow from v6.9.0 cover the manager commands themselves, or only the bundled modules?
4. What is the intended upgrade path for a team that has published and customised all modules — re-publish and re-apply, or module:diff merge?
5. Is there a supported way to consume the manager without the bundled Post/Menu/ActivityLog modules and their transitive dependencies?

Integration Approach

Stack fit. Only pursue this if at least two of the following hold: the application is greenfield on Laravel 12/13; the team has already committed to the Laravel Starter structure; there is a real need for runtime module enable/disable and manifest-driven dependency ordering; and the team accepts forking published modules as a normal, ongoing activity. If the driver is merely "we want Modules/ folders," use a lightweight alternative and avoid the bundled domain payload.

Migration path. There is no incremental retrofit story. The realistic paths are:

• Greenfield / starter-based: adopt directly; the manager's conventions are the application's conventions from day one.
• Existing application: do not attempt to modularise in place with this package. Either extract modules into a new starter-based application, or defer adoption until a boundary (new subsystem, new team) justifies it. Retrofitting Modules/ PSR-4 autoloading, route registration, and service-provider boot order onto a mature app/ tree is a multi-sprint effort whose cost the package does not reduce.

Compatibility.

• Excludes nwidart/laravel-modules and any other Modules/-namespace convention. Choose one and document the choice in an ADR.
• Composer autoload: Modules\ must be registered in composer.json; stale autoload is the single most common failure (the README's own troubleshooting section leads with dump-autoload).
• Config/route/view caches must be cleared on every deploy that touches modules; this constrains zero-downtime deployment design.

Sequencing.

1. Spike (1 week). Fresh Laravel 12 app, install, module:publish one low-risk module (Tag or Category), instrument what breaks. Do not publish Post or Menu — they carry the transitive dependency weight.
2. Contract definition. Define the module.json schema as an internal standard: naming, priority bands (e.g. 10 core, 5 UI, 0 content), and a requires policy. Freeze it before more than one team writes manifests.
3. CI gate. Add composer dump-autoload, module:status, module:dependencies, and module:detect-updates to CI. Fail the build on unsatisfied dependencies and on unpublished migrations. This is non-negotiable — it converts a manual checklist into an enforced invariant.
4. Pilot one real module in production behind a feature flag, with its migrations tracked from a recorded baseline.
5. Upgrade drill. Before scaling to more modules, rehearse one framework-major upgrade (Laravel 12→13) and one package major (v7-style breaking dependency change) to measure real cost.
6. Scale only after steps 1–5 produce a cost number you are willing to repeat per module.

Operational Impact

Maintenance. The ongoing cost is not the package — it is the forks. Every published module is your code now. Budget a standing allocation for: re-vendoring on package releases, reconciling module:diff output after upgrades, and re-applying local patches post-publish. The v7.0.0 changelog is the cautionary example: a dependency promotion required every downstream application to edit composer.json and consult UPGRADE.md. If the maintainer ships a v9 with another manifest change, you absorb it across every module you have published.

Support. GitHub issues only, one maintainer, no commercial backing, no SLA. Effectively: you support it. Treat the repository as a reference implementation to fork rather than a vendor dependency to rely on. Mitigation is to pin exact versions and vendor-lock, not to track ^ ranges — the release cadence (frequent minor bumps, several stub-only releases) is not a stability signal.

Scaling. Module count scales acceptably — priority ordering and requires resolution are cheap. What does not scale is the human process: N published modules means N drift surfaces, N migration baselines, and N upgrade rehearsals. Past roughly 8–12 actively changing modules, expect the module registry to become a governance artefact requiring an owner. Note also that module:build scaffolds structure but not wiring — there is no evidence of route-collision or table-prefix safeguards, so naming discipline is a manual control.

Failure modes to instrument for.

• Stale autoload / cache — module invisible after deploy; mitigated by CI and deploy hooks, not by process.
• Migration baseline divergence — tracked state and actual schema disagree; highest-blast-radius failure, undocumented recovery.
• Dependency cycle in requires — unclear whether detected or silently mis-ordered at boot.
• Namespace rewrite collision on publish — module:diff may not surface as a conflict, only as unexpected behaviour.
• Transitive upgrade — a spatie/laravel-activitylog or intervention/image-laravel bump breaks the bundled Post module's LogsActivity or Jodit image handling without touching your code.
• Upstream abandonment — no successor maintainer, no fork with traction. Exit plan is a hard fork of the manager itself, which is feasible at this codebase size but should be a named contingency, not an assumption.

Ramp-up. A mid-level Laravel developer reaches productive use in roughly one to two days: install, read module:help, publish one module, understand the module.json contract. Full fluency — including the migration-tracking workflow and publish/diff discipline — is closer to one to two weeks of real module work. The README is good on commands and thin on semantics: it tells you what module:detect-updates does, not what state it maintains or how to repair it. Plan for one engineer to own the module system as a named responsibility; the failure mode of an unowned module registry is silent divergence discovered during a production deploy.