Composer Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the plugin to your project’s composer.json under "extra": {"plugins": {"phar-io/composer-plugin": {}}}. Requires Composer ≥1.0.

   composer require phar-io/composer-plugin --dev
   

2. First Use Case: Use it to build a PHAR from your project. Create a phar.php script in your project root:

   <?php
   require __DIR__.'/vendor/autoload.php';
   $phar = new Phar(__DIR__.'/myapp.phar');
   $phar->startBuffering();
   $phar->addFile(__DIR__.'/src/YourClass.php', 'YourClass.php');
   $phar->setStub($phar->createStub('index.php'));
   $phar->stopBuffering();
   

   Run it via:

   php phar.php
   

3. Where to Look First:

   • Phar Documentation (core PHAR concepts).
   • vendor/phar-io/composer-plugin/src/Phar.php (plugin’s core logic).
   • Composer’s extra.plugins schema for configuration.

Implementation Patterns

Workflow: PHAR-Based Deployment

1. Composer Script Integration: Hook into post-install-cmd or post-update-cmd in composer.json to auto-generate PHARs:

   {
     "scripts": {
       "post-install-cmd": [
         "Phar\\build --output=dist/myapp.phar --main=src/index.php"
       ]
     }
   }
   

   Use --exclude-vendor to skip vendor dir or --include-vendor to bundle dependencies.

2. Custom Build Logic: Extend the plugin by subclassing Phar\Builder:

   use Phar\Builder;
   use Phar\Builder\Exception\BuildException;
   
   class CustomBuilder extends Builder {
       protected function getFiles() {
           return [
               'src/' => 'src/',
               'config/app.php' => 'config/app.php',
           ];
       }
   }
   

   Register it in composer.json:

   {
     "extra": {
       "plugins": {
         "phar-io/composer-plugin": {
           "builder": "CustomBuilder"
         }
       }
     }
   }
   

3. Dependency Management:

   • Use --include-dev to bundle dev dependencies (rare, but useful for dev tools).
   • Exclude large files with --exclude-file=tests/*.

4. Stub Customization: Override the default index.php stub by passing --stub=path/to/custom-stub.php.

Gotchas and Tips

Pitfalls

1. Stub File Requirements:

   • The stub must be a valid PHP file that calls Phar::mapPhar().
   • Example minimal stub:

     <?php
     Phar::mapPhar();
     require 'phar://myapp.phar/index.php';
     

2. Filesystem Permissions:

   • Ensure the target directory is writable. PHARs often fail silently if permissions are insufficient.

3. PHP Version Compatibility:

   • The plugin was last updated for PHP ≤7.2. Test thoroughly on PHP 8.x (may require polyfills for PharData changes).

4. Composer Cache Issues:

   • Clear Composer’s cache (composer clear-cache) if builds fail intermittently.

Debugging

• Verbose Output: Use --verbose with the plugin to see excluded/included files:

  composer phar --verbose
  

• Dry Runs: Simulate builds with --dry-run to validate file lists without writing.

Extension Points

1. Pre/Post-Build Hooks: Use Composer’s post-autoload-dump to run custom logic after PHAR generation:

   {
     "scripts": {
       "post-autoload-dump": [
         "@php phar-verify.php"
       ]
     }
   }
   

2. Custom Metadata: Embed metadata (e.g., version) via Phar::addMetadata() in a post-build script.

3. Signing PHARs: Combine with openssl to sign PHARs for distribution:

   openssl dgst -sha256 -sign key.pem -out myapp.phar.sig myapp.phar
   

Config Quirks

• Plugin Auto-Discovery: The plugin must be listed under "extra.plugins"—omitting it will cause silent failures.
• Legacy Composer: Requires Composer ≥1.0. Older versions may throw ClassNotFound errors.