Embedded Composer Core Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require dflydev/embedded-composer-core
   

   Requires PHP 7.4+ and Composer (for embedding its core functionality).

2. First Use Case Use the package to embed Composer’s core logic in a custom script or application (e.g., a CLI tool, installer, or build system) without requiring Composer as a standalone dependency. Example:

   use Dflydev\EmbeddedComposer\Core\Composer;
   
   $composer = new Composer();
   $composer->run(['install', '--prefer-dist']);
   

3. Where to Look First

   • src/Composer.php: Entry point for embedding Composer’s core.
   • tests/: Demonstrates usage patterns (e.g., running commands, handling output).
   • README.md: Basic setup and CLI integration hints.

Implementation Patterns

Core Workflows

1. Embedding Composer Logic Use the Composer class to execute Composer commands programmatically:

   $composer = new Composer(['--no-interaction']);
   $composer->run(['update', 'vendor/package']);
   

2. Custom Command Execution Extend functionality by wrapping commands in your application’s workflow:

   $composer = new Composer();
   $exitCode = $composer->run(['validate']);
   if ($exitCode !== 0) {
       throw new RuntimeException('Composer validation failed');
   }
   

3. Integration with Laravel Artisan Create a custom Artisan command to leverage Composer:

   use Dflydev\EmbeddedComposer\Core\Composer;
   use Illuminate\Console\Command;
   
   class InstallDependencies extends Command {
       protected $signature = 'app:install';
       public function handle() {
           $composer = new Composer();
           $composer->run(['install', '--optimize-autoloader']);
       }
   }
   

4. Handling Output/Errors Capture Composer output for logging or user feedback:

   $composer = new Composer(['--verbose']);
   $output = $composer->run(['show', '-i']);
   $this->info($output);
   

Advanced Patterns

• Dependency Management: Use the embedded Composer to resolve/lock dependencies in a custom installer.
• Pre/Post-Install Scripts: Hook into Composer lifecycle events (e.g., post-install-cmd) via the embedded instance.
• Isolated Environments: Run Composer in a temporary directory or containerized environment using the embedded core.

Gotchas and Tips

Pitfalls

1. Environment Assumptions

   • The embedded Composer may fail if critical system tools (e.g., git, curl) are missing. Validate dependencies explicitly:

     if (!file_exists('/usr/bin/git')) {
         throw new RuntimeException('Git is required for Composer');
     }
     

2. Configuration Conflicts

   • Embedded Composer uses composer.json from the current working directory. Ensure the file exists or provide a custom path:

     $composer = new Composer(['--config-file=/path/to/composer.json']);
     

3. Memory/Performance

   • Embedding Composer loads its full core, which can be heavy. Use --optimize-autoloader to mitigate:

     $composer->run(['dump-autoload', '--optimize']);
     

4. Output Handling

   • By default, output is streamed to STDOUT. Redirect to a file or buffer if needed:

     $composer = new Composer(['--no-ansi', '--quiet']);
     ob_start();
     $composer->run(['show']);
     $output = ob_get_clean();
     

Debugging Tips

• Verbose Mode: Enable for detailed logs:

  $composer = new Composer(['--verbose']);
  

• Exit Codes: Check $composer->run() return values (non-zero indicates failure).
• Temporary Config: Override settings via CLI args:

  $composer = new Composer(['--repository-url=https://custom.pkg.example']);
  

Extension Points

1. Custom Composer Class Extend Dflydev\EmbeddedComposer\Core\Composer to add domain-specific methods:

   class CustomComposer extends Composer {
       public function installDependencies(array $packages) {
           $this->run(['require'] + $packages);
       }
   }
   

2. Event Listeners Hook into Composer events (e.g., post-update-cmd) by extending the class and overriding event handlers.

3. Dependency Isolation Use the embedded Composer to generate a vendor/ directory in a temporary location, then symlink it into your project.

Config Quirks

• Global Config: Embedded Composer respects ~/.composer/config.json but may override it with CLI args.
• Cache Directory: Defaults to system temp dir. Specify a custom cache path if needed:

  $composer = new Composer(['--cache-dir=/custom/cache']);