- What does barryvdh/composer-cleanup-plugin actually do?
- It is a Composer lifecycle plugin, not a Laravel package, so it registers no service provider and adds zero runtime footprint. After each package is unpacked into vendor/, it hooks Composer's post-package-install and post-package-update events and deletes dev-only files such as tests, documentation, examples, PHPUnit configs, CI metadata and leftover .git directories. The result is a smaller vendor/ tree and a leaner deployment artifact, with no change to application behavior.
- How do I install composer-cleanup-plugin in a Laravel project?
- Add it as a dev dependency in your root composer.json with composer require --dev barryvdh/composer-cleanup-plugin. Then add cleanup rules under the extra.cleanup key, typically a broad * default with narrow per-package overrides. Because it only affects the build artifact, it belongs in require-dev and should never be a production dependency.
- Why do I need a config.allow-plugins entry for this package?
- Composer 2.2 and later block third-party plugins unless they are explicitly allowlisted in config.allow-plugins. Without an entry, the plugin is skipped during non-interactive CI installs and your build still reports success, so cleanup never happens. Add the package name to the allowlist and verify after installation that files were actually removed.
- Which files does the plugin remove from vendor by default?
- The default rules target non-runtime content inside each installed package: test suites, documentation folders, examples, PHPUnit and CI configuration files, and .git metadata. You configure the behavior yourself through the extra.cleanup rules block rather than relying on a fixed default. Because the rules are glob-based, an over-broad pattern can remove more than you intended.
- Can I keep LICENSE files and protect autoloaded source directories from being deleted?
- Yes, but only if you write narrow rules, because blanket patterns like *.md or docs/ also strip LICENSE files and attribution text. Blanket removal can conflict with SBOM generation and open-source license obligations for the artifact you ship. Also avoid deleting inside PSR-4 autoload roots, since that interacts badly with --optimize-autoloader and --classmap-authoritative. Verify that your rules support negation or exclusion before relying on them.
- Is it compatible with --no-dev, --prefer-dist, --optimize-autoloader and --classmap-authoritative?
- The plugin runs on Composer's package install and update events, so it works alongside --no-dev, --prefer-dist and --optimize-autoloader in principle. Note that --no-scripts does not disable plugins, so cleanup still runs, while --no-plugins disables it entirely. Test the exact flag combination your pipeline uses on one representative service before rolling it out, and check that no post-install-cmd or post-autoload-dump script depends on files the plugin deletes.
- Why is the plugin silently doing nothing in our CI pipeline?
- The most common cause is a missing config.allow-plugins entry, which makes Composer skip the plugin without failing the build. The second most common cause is a security-hardened CI image that passes --no-plugins globally, which disables cleanup while every log line still looks clean. Add an explicit assertion, such as a file-count or vendor-size check, so a silent no-op fails the pipeline instead of passing it.
- How much disk space does it save, and does it reduce download size?
- Savings show up on disk and in the built artifact only. Composer still downloads and caches the full dist archives, so install bandwidth and Packagist egress are unchanged. Measure the baseline versus post-cleanup delta in vendor bytes, file count, container image size and artifact size on one representative service before assuming the gain is meaningful.
- Does it work with path repositories or symlinked packages?
- Be careful here. With path repositories or --prefer-source, cleanup writes through symlinks and mutates your actual local package checkout rather than a throwaway artifact copy. That can corrupt a shared working copy used by other builds or developers. If path repositories appear anywhere in your build matrix, exclude them or skip the plugin for those installs.
- Is composer-cleanup-plugin still maintained, and what are the alternatives?
- The repository is archived, with its last release in August 2023 and no active upstream maintenance, so a future Composer or PHP major release could break it with no fix. There is no patch path, meaning you would need to fork it if it becomes load-bearing. Alternatives include a multi-stage Docker build, a CI cleanup shell step, or composer install --no-dev --prefer-dist --optimize-autoloader, which often clears size constraints without install-time code execution.