Module Installer Laravel Package

Technical Evaluation

What it is. A Composer plugin (not a runtime library) that registers a custom installer for packages declaring "type": "saucebase-module". Two moving parts: src/Installer.php (implements supports() / getInstallPath() to route installs to modules/<name> lowercased, with a configurable base directory) and src/Plugin.php (Composer plugin lifecycle: activate/deactivate/uninstall). Zero runtime footprint — it only executes during composer install / require / update.

Architecture fit. Fits only if Sauce Base has deliberately chosen an out-of-vendor module model — application code living in modules/, versioned and resolved by Composer. That is a legitimate and increasingly common pattern (Drupal, WordPress via composer/installers, Laravel modular monoliths), but the installer is the smallest piece of that architecture. It solves path placement only. It does not solve:

• autoloading (PSR-4 for modules/* must be declared in the root composer.json or generated by a companion package),
• Laravel package discovery (php artisan package:discover scans vendor/, so extra.laravel.providers in a module will not be auto-registered without a separate registration mechanism),
• module enable/disable, dependency ordering, or asset publishing.

Verdict: architecturally coherent as a building block, incoherent as a product on its own. Its value is entirely contingent on a companion runtime (saucebase/core or equivalent) that closes the autoload/discovery gap. Confirm that companion exists before evaluating further.

Integration feasibility. Low technical effort, moderate governance effort.

• Technical: adding "type": "saucebase-module" to a package and running composer require is trivial. Configuring the base dir is presumably an extra key in the root composer.json — needs confirmation from source, as it is not documented in the provided excerpts.
• Governance (the real friction): Composer 2.2+ blocks plugins by default. Every developer machine and every CI image must carry "config": { "allow-plugins": { "saucebase/module-installer": true } }, otherwise installs silently place modules in vendor/ or fail. This is the single most common support ticket you will generate.
• Build pipeline: --no-plugins and --no-scripts flags, hardened CI images, and some Docker build patterns will break module placement. Any environment with a locked-down Composer config is a blocker.

Technical risk.

Key questions for the maintainer/architect.

1. What is the complete module contract — is there a saucebase/core package that handles PSR-4 autoloading, provider registration, migrations, and asset publishing? Without it, this package alone delivers no functional value.
2. Why a custom installer rather than composer/installers with installer-paths ("modules/{$name}")? What does the bespoke plugin add — the lowercase normalization, the configurable base dir, or both?
3. Where is the base directory configured (extra schema key, env var, CLI)? Is the schema documented and validated?
4. What is the exact package-name → directory transformation? How are vendor prefixes handled (the test suite references a "missing module vendor prefixes" error), and how are collisions and traversal attempts rejected?
5. Are composer-plugin-api constraints pinned to ^2.x? Is Composer 1 explicitly unsupported?
6. What is the supported-version policy and the deprecation/upgrade path if the install location scheme changes (e.g., modules/ → app-modules/)? Composer will not relocate already-installed paths.
7. Is Plugin::uninstall implemented to remove empty parent directories, and is modules/ gitignored in the reference project?
8. Who else consumes this today, and what is the actual production track record behind the 0 dependents figure?

Integration Approach

Stack fit. Appropriate only for Laravel/PHP 8.2+ (PHPUnit 12 and Pint/Laravel preset in the repo imply a modern runtime) projects that have already committed to a Composer-resolved, out-of-vendor module layout. It is a build-time dependency, so it does not constrain runtime framework versions, but it does constrain the project's Composer configuration and therefore its CI and developer onboarding.

Migration path. Treat this as a new-project-only decision first; retrofit is where cost lives.

1. Greenfield: add the plugin, set allow-plugins, define the module base dir in extra, and — critically — pre-wire autoloading before the first module is installed. Validate with one throwaway module end-to-end (install → autoload → provider registered → route/migration works).
2. Brownfield (modules currently in vendor/ or in a hand-managed modules/ dir): requires a one-time relocation. composer.lock references vendor paths; a plain composer update after adding the plugin should re-place packages, but any local/non-published modules need a path repository entry plus explicit directory move. Expect a manual, reviewed commit — not an automated one. Do this on a branch, verify git status shows renames not deletions, and confirm no module was left orphaned in vendor/.
3. Abort path: because the code surface is ~2 classes and MIT, removal is cheap — switch module packages to a path repository with explicit installer-paths or to composer/installers. Keep the module directory naming convention stable so a swap doesn't churn files.

Compatibility.

Sequencing.

1. Spike (½–1 day): read src/Installer.php and src/Plugin.php; confirm base-dir config key, name transformation, and traversal handling. Run the existing PHPUnit suite locally.
2. Reference integration (1–2 days): one real module installed end-to-end in a scratch Laravel app, including provider registration and a migration. This is the go/no-go gate — if discovery requires bespoke glue, that glue is the actual deliverable, not this package.
3. Build-vs-buy decision: side-by-side with composer/installers + installer-paths. Only proceed if the bespoke plugin demonstrably removes complexity.
4. Pilot (1 squad, 1–2 weeks): developer onboarding docs covering allow-plugins, IDE/indexing of modules/, and .gitignore; collect friction.
5. Standardize: codify allow-plugins, base-dir config, and module naming in the project template / scaffold repo so the decision is made once, not per-project.
6. Defer any multi-repo or cross-team rollout until a second team has run the pilot cleanly.

Operational Impact

Maintenance. Low code surface, clear structure: src/ with Installer.php, Plugin.php, and src/Exceptions/; PHPUnit 12 suite under tests/ mirroring the namespace and mocking Composer collaborators; Pint (Laravel preset) for style; composer validate in the checks. Conventional Commits and focused PRs are documented in AGENTS.md. Ongoing cost is therefore small in absolute terms — but it is externally owned with ~1 star and 0 dependents, so you cannot rely on upstream responsiveness. Budget for the possibility of vendoring or forking (~a day of engineering) rather than assuming patches arrive. Recommended: pin to a tag, review diffs on upgrade, and keep an internal fork branch ready.

Support. The dominant support load will not be bugs — it will be configuration and comprehension:

• "Install failed / module went to vendor/" → missing allow-plugins entry.
• "Module installed but its service provider isn't registered" → autoload/discovery gap, which is outside this package's scope and will be misattributed to it.
• "IDE doesn't index modules/" → missing PSR-4 mapping or excluded-folder settings.
• "Directory name is wrong case" → normalization surprising someone.

Each of these is a documentation problem. If the team cannot produce a one-page "modules layout" doc plus a scaffolded composer.json, support cost will exceed the plugin's value. Assign a named internal owner; there is no community to escalate to.

Scaling. Effectively unlimited — it is a build-time path resolver with no runtime cost, no database, no network, no concurrency. Scaling concerns are organizational rather than technical:

• Module count: dozens or hundreds of directories under modules/ is fine for Composer, but IDE indexing, static analysis, and test-suite runtime become the real bottlenecks.
• Team count: the layout convention must be centralized in a shared template. Divergent base-dir configs across repos would be the scaling failure mode.
• CI fan-out: every pipeline that installs dependencies must permit the plugin; drift in CI base images is the most likely scaling regression.

Failure modes.

Ramp-up. Very low for a developer who has seen Composer plugins before — under an hour including reading both source files. For everyone else, the ramp is about the convention, not the plugin: expect a half-day of orientation covering where modules live, why they are outside vendor/, how allow-plugins interacts with onboarding, how autoloading is wired, and how to create a new module from a template. The highest-leverage onboarding artifact is not documentation of this package — it is a working scaffold repo where composer install produces a functioning module-enabled application on the first try. Ship that before shipping the plugin.