msomnium/vendor-packer

Package all vendor files into a single .phar file

0.1.0-alpha2 2026-04-04 06:30 UTC

Requires

• composer-plugin-api: ^2.0
• humbug/box: 4.6.7

Requires (Dev)

• composer/composer: ^2.0

MIT

• ArielLeyva

README

VendorPacker

VendorPacker is a Composer plugin that allows you to package your entire vendor/ directory into a single .phar file.
It provides a clean workflow for packing, removing, regenerating, and recreating your dependencies, while keeping full compatibility with Composer and the PHP ecosystem.

1. Installation
2. Usage Examples
3. Available Commands
   1. vendor:pack
   2. vendor:update-autoload
   3. vendor:remove
   4. vendor:regenerate
   5. vendor:recreate
4. Optional Configuration Files
   1. vendor-packer-config.json
   2. vendor-packer-stub.php
5. Limitations
6. Advantages
7. How It Works Internally

VendorPacker is especially useful for:

• Deployments where the vendor/ folder must be minimized or removed
• Hosting environments with file count limits
• Projects that need a portable, self‑contained dependency bundle
• Reducing deployment size and improving autoload performance
• Ensuring reproducible builds

Installation

VendorPacker is distributed as a Composer plugin and requires no global tools or manual setup. Box is bundled automatically as a dependency of the plugin.

composer require msomnium/vendor-packer

Usage Examples

Below are the most common workflows using VendorPacker.

composer vendor:pack
composer vendor:update-autoload
composer vendor:remove

These three commands package all your dependencies into a single .phar file, significantly reducing the number of inodes in your project.

All your dependencies remain available and you don't need to make any adjustments to your project.

Available Commands

VendorPacker provides this commands into your Composer environment:

1. vendor:pack

Pack vendor folder content into a .phar file.

composer vendor:pack

This command uses Box for compile your vendor content folder into a single .phar file. You can customize the Box compilation settings by creating a valid configuration file for the box in your project's root directory; the name of this file should be vendor-packer-config.json.

For example, this configuration creates a .phar file compressed with the BZ2 algorithm.

{
  "stub": "vendor-packer-stub.php",
  "directories": [
    "vendor"
  ],
  "output": "vendor/vendor-packer.phar",
  "compression": "BZ2"
}

Warning

The output file must always be vendor/vendor-packer.phar

By default, VendorPacker creates a stub file for Box. This file only loads the autoload from the generated .phar file so that all dependencies are available. You can customize this behavior with a vendor-packer-stub.php file in your project's root directory.

2. vendor:update-autoload

Update the vendor/autoload.php file to point to the new .phar file.

composer vendor:update-autoload

This replaces the default Composer autoloader with a lightweight proxy that loads the .phar file generated instead of the physical vendor directory.

3. vendor:remove

Delete the entire vendor/ folder content.

composer vendor:remove

Remove all files and directories of your installed dependencies.

Warning

Use only after running vendor:pack

4. vendor:regenerate

Regenerate the .phar file from the current vendor folder content.

composer vendor:regenerate

This is equivalent to re‑packing the vendor directory without reinstalling dependencies.

5. vendor:recreate

Reinstall all dependencies in your vendor folder.

composer vendor:recreate

This command runs composer install in your project root, restoring a full vendor directory from scratch.

Optional Configuration Files

VendorPacker supports two optional files in your project root:

vendor-packer-config.json

Custom Box configuration for advanced use cases. See the Box Configuration for more information.

If present, VendorPacker will use this file instead of generating its own default configuration.

You can use this to:

• Add custom finders
• Exclude or include specific files
• Modify PHAR metadata
• Override compression settings

vendor-packer-stub.php

Custom PHAR stub file.

If present, VendorPacker will use your stub instead of the default one.
This allows you to:

• Customize the PHAR bootstrap process
• Load additional files before the autoloader
• Implement custom runtime logic
• Integrate with frameworks or custom loaders

Limitations

VendorPacker works with the vast majority of Composer packages, but there are rare edge cases:

1. Packages that write into their own vendor subdirectory at runtime

Some libraries (very uncommon) may:

• Generate cache files inside their own vendor folder
• Write temporary files next to their source code
• Expect writable paths inside vendor/

Since .phar files is read‑only, these packages may not behave correctly.

1. PHAR extension deisabled

VendorPacker uses the PHP PHAR extension for read operations; some shared hosting services or servers do not have the PHAR extension enabled; please verify that this extension is activated on your server or hosting provider.

1. Write .phar file permission (partial limitation)

Some servers or hosting providers disable writing to .phar files. In these cases, the composer vendor:pack and composer vendor:regenerate commands will not work. If you encounter this limitation, you can always generate the .phar file on your device and upload it to your server.

Recommendation:
Test thoroughly before deploying PHAR‑only mode.

Advantages

VendorPacker provides several strong benefits:

• Deployment simplicity: Ship a single .phar file instead of thousands of files.
• Faster deployments: Copying one file is significantly faster than syncing an entire vendor tree.
• Reduced file count: Ideal for shared hosting, serverless, or inode‑limited environments.
• Reproducible builds: The PHAR ensures dependencies are packaged exactly as installed.
• Cleaner project structure: You can remove the vendor folder entirely after packing.
• Fully reversible: Restore the vendor directory anytime with vendor:recreate.
• Higher performance: Using a single .phar file to package dependencies makes Composer and PHP read operations faster.

How It Works Internally

VendorPacker follows a simple and predictable workflow.
Here’s what happens inside your project when you run the three main commands:

1. composer vendor:pack

This command creates the vendor/vendor-packer.phar file.

Internal flow:

1. VendorPacker generates a temporary Box configuration (unless you provide vendor-packer-config.json).
2. It loads your custom stub (vendor-packer-stub.php) or uses the default one.
3. It executes Box with the project root as the working directory.
4. Box scans the vendor/ directory and packages it into vendor/vendor-packer.phar.
5. Temporary files are cleaned up.

Result:
Your entire vendor directory is now compressed into a single .phar file.

2. composer vendor:update-autoload

This command switches your project to PHAR‑based autoloading.

Internal flow:

1. VendorPacker replaces vendor/autoload.php with a lightweight proxy.

2. The proxy loads:

   phar://vendor/vendor-packer.phar/vendor/autoload.php
   

3. Your application now uses the PHAR’s internal autoloader instead of the physical vendor directory.

Result:
Your project runs using vendor-packer.phar transparently, without modifying your application code.

3. composer vendor:remove

This command removes the physical vendor directory.

Internal flow:

1. VendorPacker deletes everything inside vendor/
2. It preserves only:
   • vendor/vendor.phar
   • vendor/autoload.php (the proxy)

Result:
Your project now runs entirely from the PHAR, with no vendor folder present.