Burgomaster Laravel Package

Technical Evaluation

Architecture Fit

• Modularization & Microservices: Burgomaster aligns with Laravel’s modularity goals by enabling self-contained PHAR/ZIP distributions of components (e.g., APIs, CLI tools, or libraries). Ideal for decomposing monoliths into reusable, versioned packages while preserving Laravel’s ecosystem.
• Dependency Isolation: PHARs encapsulate vendor dependencies, reducing conflicts in shared environments (e.g., SaaS multi-tenancy). However, Laravel’s service container and Eloquent cannot be fully encapsulated in a PHAR without custom stubs.
• Performance Tradeoffs: PHARs offer ~30–50% smaller footprint than ZIPs (via compression) and faster cold starts (no Composer autoloading), but no benefit for web requests (Laravel’s OPcache dominates). Use case: CLI tools, edge-cached APIs, or offline scripts.
• Anti-Patterns:
  • Not for web apps: PHARs cannot dynamically load Blade views or handle runtime config changes.
  • Debugging overhead: Stack traces reference phar:// paths, complicating Laravel’s debugbar or telescope.
  • Security risks: PHARs require phar.readonly=0 (disabled by default in many PHP configs).

Integration Feasibility

• Laravel-Specific Challenges:
  • Service Providers: PHARs cannot use Laravel’s container; require manual registration via stub files.
  • Artisan Commands: Must be pre-registered in the PHAR stub (e.g., phar://stub.txt).
  • Environment Configs: .env files cannot be bundled (use --exclude=.env and pass configs at runtime).
• Tooling Synergy:
  • Composer: Works as a pre-step (run composer install before packaging).
  • Laravel Mix: Can bundle assets into the PHAR (e.g., burgomaster package --include=public/).
  • CI/CD: Integrates with GitHub Actions/GitLab CI via burgomaster package in workflows.
• Alternatives:
  • Docker: Better for web apps (PHARs add no value).
  • Composer’s dump-autoload: Simpler for traditional deployments.
  • Box/Phar-IO: More Laravel-friendly PHAR tools (e.g., humbug/box).

Technical Risk

Key Questions

1. Strategic Alignment:
   • Does this support our modularization roadmap (e.g., microservices, plugins)?
   • Will PHARs reduce deployment complexity (e.g., for clients without Composer access)?
2. Laravel-Specific:
   • Can we package Artisan commands as PHARs for distribution?
   • How will service providers be initialized in a PHAR (stub files vs. custom bootstrappers)?
3. Operational:
   • Who will manage PHAR signing keys and rotate them?
   • How will we handle PHAR updates in production (rolling restarts vs. immutable deployments)?
4. Performance:
   • Have we benchmarked PHAR vs. Composer autoloading for our use case?
   • Will PHARs reduce cold-start latency for CLI tools or APIs?
5. Security:
   • Are PHARs allowed in our runtime environment (phar.readonly=0)?
   • How will we validate PHAR integrity post-deployment?

Integration Approach

Stack Fit

• Ideal Use Cases:
  • Laravel CLI Tools: Package Artisan commands as distributable PHARs (e.g., php my-command.phar migrate).
  • Third-Party Plugins: Sell Laravel add-ons as self-contained PHARs (e.g., php payment-gateway.phar:process).
  • Legacy Migration: Wrap monolithic PHP scripts into PHARs for easier maintenance.
  • Edge Deployments: Cache PHARs in CDNs for offline-capable APIs (e.g., phar://api.phar).
• Poor Fit:
  • Traditional Laravel Web Apps: Overkill (use Docker/Composer instead).
  • Dynamic Code: PHARs cannot load Blade templates or runtime-generated classes.
  • High-Churn Environments: PHARs are immutable; prefer containers for frequent updates.
• Complementary Tools:
  • Composer: Manage dependencies before PHAR generation.
  • PHPStan: Ensure PHAR-compatible code (no dynamic eval or class_alias).
  • GitHub Actions: Automate PHAR builds on tag pushes.

Migration Path

1. Pilot Phase (2–4 Weeks):

   • Scope: Package a non-critical Laravel CLI tool (e.g., a custom Artisan command).
   • Steps:
     1. Install Burgomaster: composer require mtdowling/burgomaster.
     2. Create a PHAR stub (phar://stub.txt) to register the command:

        <?php
        if (php_sapi_name() === 'cli') {
            require __DIR__ . '/vendor/autoload.php';
            $command = new \App\Console\Commands\MyCommand();
            $command->handle();
        }
        

     3. Build the PHAR:

        burgomaster create my-command.phar --stub=phar://stub.txt --main=vendor/bin/my-command
        

     4. Test locally and in a staging environment.

2. Incremental Rollout:

   • Phase 1: Package vendor dependencies only (exclude Laravel core).

     burgomaster create my-library.phar --exclude=app/,config/,resources/
     

   • Phase 2: Bundle entire app (if justified), but exclude:
     • bootstrap/cache/ (generated files).
     • storage/ (runtime data).
     • .env (environment configs).
   • Phase 3: Automate PHAR signing and validation in CI:

     # GitHub Actions Example
     - name: Build PHAR
       run: burgomaster create my-app.phar --sign --signer=key.pem
     - name: Validate PHAR
       run: php -r "if (!phar_validate_signature('my-app.phar')) exit(1);"
     

3. Fallback Plan:

   • Maintain a Composer-based fallback for non-PHAR deployments.
   • Use feature flags to toggle PHAR vs. traditional deployments.

Compatibility

Sequencing

1. Pre-Integration:
   • Audit Codebase:
     • Remove dynamic class loading (e.g., eval, class_alias).
     • Exclude non-PHAR-friendly files (e.g., .env, bootstrap/cache/).
   • Update composer.json:

     {
       "scripts": {
         "post-autoload-dump":