Composer Installer Laravel Package

Technical Evaluation

Architecture fit. This is a Composer install-path plugin for the Liberu Laravel boilerplate: it redirects packages whose type is liberu-module/liberu-theme (or equivalent) so they land in modules/ and themes/ rather than vendor/. That is a legitimate and well-trodden pattern for modular Laravel monorepos, but it is a build-time dependency that sits underneath every other package decision — it is not a leaf library. The 1.1.0 addition of extra.plugin-modifies-install-path is the single most architecturally significant change: it declares to Composer that this plugin mutates install paths, so Composer no longer assumes vendor/ during the planning phase. The release notes describe the prior symptom precisely — "unexplained churn in the tracked package directories" — which is the classic signature of a plugin being activated after path resolution. This is a correctness fix, not a feature, and it materially reduces the class of nondeterministic installs.

Integration feasibility. High. Adoption is a single composer require plus a plugin allow-list entry (config.allow-plugins) in the root project; there is no application code to change and no runtime surface. The injectable root directory on LiberuInstaller is a testability affordance only, and by defaulting to getcwd() it preserves exact prior behaviour — a well-behaved non-breaking API change. Removal of Composer\Plugin\Capable is safe: the interface declared no capabilities, so no consumer could have depended on getCapabilities() returning anything meaningful. The real integration question is not "can we install it" but "can we install it and keep our existing modules/ tree intact," which the new collision check directly governs.

Technical risk.

• Breaking-by-design rename behaviour. The collision check inspects the target directory's composer.json; if it names a different package, the install fails. This converts a silent overwrite into a hard stop — correct, but it means any package we have ever renamed while keeping its install path becomes a blocked install until someone runs rm -rf on the old target. Note the asymmetry: the release ships the detection but not a remediation command, so the upgrade instruction is literally manual recursive deletion in a tracked directory.
• Fail-open ownership semantics. "An absent, unreadable or nameless composer.json is not treated as evidence of ownership and blocks nothing." That is the conservative choice for greenfield installs, but it means a corrupted, truncated, or permission-denied composer.json — exactly the states that follow a botched previous install — will not trigger the guard. The protection is strongest in the clean case and weakest in the messy case.
• Process-scope vs. working-tree scope. The defect being fixed was real (collision detection only saw the current process), but working-tree scanning introduces filesystem-read behaviour at install time: symlinked modules/, NFS/CI cache mounts, and case-insensitive filesystems are all untested-looking edges.
• Test coverage is new, not mature. 32 tests spanning path computation, supported types, name validation, traversal and absolute-path rejection, and both collision paths is a credible first suite — traversal and absolute-path rejection in particular show security awareness — but Pint and Pest in CI is a lint-and-unit baseline, not an integration matrix. There is no evidence of testing against multiple Composer versions or PHP versions, which is the risk that actually bites for a build-tool plugin.

Key questions. Which Composer and PHP versions are supported, and is plugin-modifies-install-path honoured on the oldest Composer we must support (it is a relatively recent extra)? What are the exact package types this installer claims, and is that list stable? Does the collision check follow symlinks? What is the operator-facing error message on collision — does it name the offending target path and the rm -rf remedy, or does it emit a bare Composer failure? Is the plugin's own version pinned in the boilerplate's composer.json, and does the boilerplate's CI exercise a from-scratch install and a rename-then-install scenario?

Integration Approach

Stack fit. Native. The package is a Composer plugin for a Laravel boilerplate; it needs no service container, no config publishing, and no artisan command. It fits the existing composer install step that already gates every deploy. The main stack-level prerequisite is that root projects allow-list the plugin — a one-line config.allow-plugins change that should be committed alongside the version bump, not discovered at deploy time.

Migration path. Low effort but not zero-touch. Recommended sequence: (1) pin to 1.1.0 explicitly in the boilerplate rather than floating, so the behavioural change is attributable; (2) audit modules/ and themes/ for directories whose composer.json name no longer matches their Composer package name — these are the future hard-failures; (3) for each, decide deliberately: delete the stale directory and reinstall, or rename the directory to match; (4) run a clean-room composer install in CI to confirm plugin-modifies-install-path takes effect and the churn disappears; (5) only then roll to developer machines and deploy pipelines. Because the failure is fail-closed at install time, a bad rollout halts builds rather than corrupting working trees — a preferable failure direction, but it does mean the audit in step 2 must precede the bump, not follow it.

Compatibility. Backward compatible for any project with a clean modules//themes/ tree and no pending renames. The only genuinely breaking scenario is the documented one: keep install path, change Composer name. The LiberuInstaller constructor change is additive. The Capable removal is inert. Worth stating plainly in the boilerplate changelog that "blocked install after rename" is intended behaviour and not a regression, because the error will otherwise be read as one.

Sequencing. Land this in the boilerplate before, or alongside, any batch of module renames — not after. Retrofitting it mid-rename leaves half the tree in the ambiguous state the guard cannot adjudicate (nameless or absent composer.json blocks nothing, so it will not save you). Pair the bump with a short runbook entry and a CI job that performs a from-scratch install.

Operational Impact

Maintenance. Modest and now materially better defended than 1.0.x: prior to this release the package had no test suite at all, which for code that rewrites install destinations was the largest single liability. Pint plus Pest in CI is a sustainable floor for a package of this size. Ongoing cost is tracking Composer's plugin and installer APIs, which do change; the plugin-modifies-install-path opt-in is itself evidence that Composer's activation ordering has shifted under this package's feet once already.

Support. Expect a predictable first wave of tickets reading "install fails after we renamed a module." The fix is a documented recursive delete, which support can script, but it involves telling developers to rm -rf a tracked directory — provide the exact command and a pre-flight check rather than leaving each team to improvise. Second wave: any environment where modules/ is a symlink or a network mount, where working-tree collision detection has unverified behaviour.

Scaling. Install-time cost is a directory read per claimed package; negligible at tens of modules, and worth a sanity check at hundreds. The CI suite scales trivially. The real scaling constraint is organisational: the more packages that declare these types, the larger the surface on which a single plugin misbehaving breaks every install in the fleet. It is a chokepoint dependency, which argues for pinning and for exercising it in the boilerplate's own CI rather than trusting upstream.

Failure modes. Ranked: (1) hard install failure on rename — loud, safe, recoverable; (2) fail-open overwrite when the target composer.json is absent, unreadable, or nameless — silent and destructive, and the residual risk this release does not close; (3) path churn if plugin-modifies-install-path is not honoured on an older Composer — silent, shows up as dirty git state; (4) traversal or absolute-path acceptance on unusual inputs — now explicitly tested, so lowered but not eliminated; (5) environment-specific behaviour on symlinked or case-insensitive filesystems — untested and unstated.

Ramp-up. Very low for a developer (requirement plus allow-list entry). Low-to-moderate for whoever owns the boilerplate: they must understand Composer's plugin activation model well enough to know why the extra flag matters, and be able to audit composer.json names against directory names. Budget half a day for the initial audit and CI wiring, and treat the error-message quality of the collision path as the deliverable that determines how much support load this generates.