Composer Cleanup Plugin Laravel Package

Product Decisions This Supports

• Deployment artifact budgeting (the one genuine decision). This package informs a single question: how small must the shipped artifact be? It applies only where a hard, named constraint exists — a serverless zip ceiling, a registry bill metered per GB, slow Lambda cold starts, or bandwidth-limited/air-gapped delivery. Treat it as a line item inside a packaging initiative, never as a standalone roadmap decision.
• Build vs. buy vs. native flags. It forces the comparison that actually matters: pinned community plugin vs. a short deterministic CI cleanup script vs. composer install --no-dev --prefer-dist --optimize-autoloader plus multi-stage Docker and .dockerignore. For most teams the answer is "native flags first, small script second," and this package rarely changes that answer.
• Roadmap scoping for platform/build tooling. If platform work is being prioritized, this is a time-boxed spike (one to two days of measurement plus a CI proof of concept), not a roadmap line item. It competes directly against leaner base images and dropping dev tooling entirely — both typically larger wins, lower risk, no third-party exposure.
• A narrow go/no-go for one constrained service. Useful as a yes/no when a specific service is measurably over a limit (e.g., a Lambda-hosted Laravel app sitting ~8 MB above the deployment cap). It does not inform product features, pricing, user-facing roadmap, or application architecture — there is no service provider, no config surface, no runtime role.
• The compliance stance the PM actually owns. Cleanup rules strip *.md, docs/, and license files. The PM must decide, before engineering writes a single glob, whether shipped artifacts must retain LICENSE text, attribution notices, and documentation for audit, SBOM, or open-source obligations. Blanket rules and those obligations are in direct conflict.
• Supply-chain governance precedent. Composer plugins execute code at install time, so adoption sets precedent for the org's allow-plugins allowlist — a platform-standard decision. An archived plugin with zero dependents is a poor precedent-setter; expect this to be approved as a scoped exception, never as a standard.
• Where the value is real and measurable: serverless package ceilings, air-gapped or bandwidth-constrained distribution, large multi-tenant fleets where per-deploy artifact bytes become registry/egress cost, and CI cache-size limits. In every case the return is bytes and money — not product capability.

When to Consider This Package

Adopt only when all of the following hold:

• A measured, specific problem exists. You have a baseline (du -sh vendor, image size, Lambda zip size) plus identified top offenders (du -sh vendor/*/* | sort -rh | head -20), and native flags do not close the gap.
• Native options are exhausted. --no-dev, --prefer-dist, --optimize-autoloader, multi-stage builds, and .dockerignore are already applied and you are still over a hard limit.
• Blast radius is one build. It runs at install time in CI or an image build, pinned to an exact version, with a documented rollback (composer install --no-plugins, or remove plugin + rules and rebuild).
• The cleaned vendor tree is validated. Full test suite, a staging smoke deploy, and a vendor manifest diff against baseline are pipeline steps — not optional.
• Legal has signed off on stripping LICENSE* and attribution files, or those patterns are explicitly excluded.
• No path repositories or --prefer-source installs are in the build matrix — cleanup writes through symlinks and mutates the local checkout.
• Ownership is assigned. A platform/build owner accepts that the package is archived, will need a fork for fixes, and holds a scheduled review against replacement.

Look elsewhere — native flags, better Docker layering, a short CI script — when:

• Savings are unmeasured or marginal. Most modern Laravel dependencies already export-ignore tests and docs; realistic wins are tens of megabytes concentrated in a handful of laggards.
• You need a maintained dependency. Last release 2023-08-05, archived, zero dependents, 144 stars — no compatibility or security fixes, including for future Composer majors.
• You are standardizing across teams. An archived install-time plugin that can block composer install org-wide — and is silently skipped when the allow-plugins entry is missing — is a bad platform standard.
• Compliance or SBOM processes audit vendor contents.
• You run path repos, heavy post-install-cmd scripting over package fixtures, or --classmap-authoritative with aggressive rules that risk deleting files under PSR-4 roots.
• Your constraint is runtime performance or application architecture. This package has no role there.
• You want the bigger win. Leaner base images and --no-dev almost always beat it, with no install-time code execution and no third-party maintenance exposure.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, archived, build-time utility that deletes tests and documentation from third-party PHP libraries before deployment, shaving megabytes off what we ship. Nothing the customer sees changes: no product behavior, no architecture, no runtime footprint. The realistic upside is modest — standard Composer flags already remove most of that weight — so remaining savings are typically tens of megabytes in a few packages. The realistic downside is a stalled build or a broken deploy caused by a plugin nobody maintains. Recommendation: do not adopt it as a standard dependency; approve a bounded pilot only if a specific service is hitting a hard package-size or storage limit, with an exact version pin, a rollback command, and a named owner.

For engineering — the short version. It is a Composer install/update lifecycle plugin, not a Laravel package: no service provider, no config publish, no runtime presence. It goes into the root project as require-dev, requires an entry in config.allow-plugins (Composer 2.2+ blocks plugins by default, and a missing allowlist entry fails silently — the build looks clean but nothing was cleaned), and is configured via glob rules under extra.cleanup.rules with a conservative default plus narrow per-package overrides. It runs after each package unpacks, so it works transparently inside a Docker RUN composer install. Pair it with --no-dev --prefer-dist --optimize-autoloader; never delete files under an autoloaded PSR-4 root; exclude LICENSE*; exclude path-repository packages; commit the lockfile; pin the exact version. Document --no-plugins as both the diagnostic and the escape hatch if installs start failing. Composer only loads plugins from the root project — putting this in a package we publish does nothing for consumers and creates confusion, so encode as policy: allowed in build pipelines, prohibited in application require blocks, prohibited in published packages.

For finance and procurement — the cost story. License cost is zero. The real cost is engineering time: baseline measurement, CI proof of concept, test and staging validation, a runbook, and periodic re-review of a frozen dependency. Weigh that against a short CI cleanup script or better Docker layering, which carry no third-party maintenance exposure at all. Approve only where the measured artifact reduction has a direct cost line attached — registry storage, egress, or a serverless package limit currently blocking a release.

For security and compliance — the risk statement. Install-time plugin execution is supply-chain surface area, and this one is archived with no dependents and no patch path; any defect becomes our fork to maintain. It can also delete license and attribution files, conflicting with SBOM or open-source obligations. Mitigations: exact version pin, committed lockfile, allow-plugins allowlist scoped to build pipelines, explicit LICENSE* exclusions, vendor-manifest diffing in CI, and a scheduled review to replace it with native flags or a CI script.