Getting Started

Minimal Steps for Laravel Developers

Installation Add Burgomaster via Composer:
```
composer require mtdowling/burgomaster
```
No Laravel-specific configuration is needed—Burgomaster works out-of-the-box with Composer projects.
First Use Case: Packaging a Laravel Artisan Command Create a PHAR of a standalone Artisan command (e.g., app/Console/Commands/MyCommand.php):
```
burgomaster create my-command.phar --main=vendor/bin/my-command
```
This generates a self-contained PHAR that consumers can run with:
```
php my-command.phar
```
Where to Look First
- CLI: Use burgomaster --help for command-line options.
- Laravel Commands: Extend Illuminate\Console\Command and package the command’s entry point.
- Documentation: Focus on the GitHub README for advanced PHAR features (e.g., stubs, signing).

Implementation Patterns

Laravel-Specific Workflows

Packaging Artisan Commands Create a PHAR for a custom Artisan command:
```
burgomaster create my-command.phar \
    --main=vendor/bin/my-command \
    --exclude=vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php
```
- Key: Use --main to point to the command’s entry point (e.g., vendor/bin/my-command).
- Tip: Exclude Laravel core files if the PHAR is for a standalone tool.
Bundling Laravel Assets Include frontend assets (e.g., JS/CSS) compiled by Laravel Mix:
```
burgomaster create my-package.phar \
    --include=public/ \
    --include=resources/js/dist/
```
- Workflow: Run npm run prod → php artisan build → package the output.

PHARs for Laravel Plugins Package a plugin as a PHAR for easy distribution:

burgomaster create my-plugin.phar \
    --main=vendor/autoload.php \
    --stub=phar://stub.txt \
    --exclude=tests/

Stub Example (stub.txt):

<?php
Phar::mapPhar('my-plugin.phar');
require 'phar://my-plugin.phar/vendor/autoload.php';

Usage: Consumers load the plugin via:

require 'phar://my-plugin.phar/src/MyPluginServiceProvider.php';

CI/CD Integration Automate PHAR generation in GitHub Actions:

- name: Build PHAR
  run: |
    composer install --optimize-autoloader
    burgomaster create my-app.phar \
        --main=public/index.php \
        --exclude=bootstrap/cache/* \
        --sign --signer=key.pem

Key: Combine with composer install --optimize-autoloader for smaller PHARs.

Debugging PHARs Test locally with:
```
burgomaster create my-debug.phar --verbose
```
- Tip: Use --verbose to inspect included/excluded files.

Integration Tips

Composer Scripts Add PHAR generation to composer.json:

"scripts": {
    "post-autoload-dump": "burgomaster create my-package.phar --main=vendor/bin/cli",
    "package": "burgomaster create my-package.zip"
}

Run with:

composer package

Laravel Service Providers For PHARs that include Laravel logic, manually register providers in the stub:

// stub.txt
<?php
Phar::mapPhar('my-package.phar');
$loader = require 'phar://my-package.phar/vendor/autoload.php';
$loader->addPsr4('MyPackage\\', 'phar://my-package.phar/src');
new MyPackage\ServiceProvider($app);

Dependency Management
- Include: Use --include to add non-Composer files (e.g., config/).
- Exclude: Use --exclude to trim bloat (e.g., node_modules, tests).
PHAR vs. ZIP
- Use PHAR for CLI tools or performance-critical packages.
- Use ZIP for web assets or when PHARs are blocked (e.g., shared hosting).

Gotchas and Tips

Pitfalls

PHAR Security
- Issue: PHARs require phar.readonly=0 in php.ini (disabled by default for security).
- Fix: Document this requirement for consumers or use ZIPs.
- Workaround: Sign PHARs with --sign and validate on load:
```
burgomaster create my-package.phar --sign --signer=key.pem
```
Dynamic Code
- Issue: PHARs cannot load classes dynamically (e.g., class_alias, eval).
- Fix: Use static analysis (PHPStan) to catch violations:
```
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse --level=7
```
Laravel-Specific Quirks
- Issue: PHARs cannot load config/ or routes/ dynamically.
- Fix: Bake configs into the PHAR stub or use environment variables:
```
// stub.txt
<?php
putenv('APP_ENV=production');
```
Dependency Bloat
- Issue: PHARs include all vendor/ dependencies, increasing size.
- Fix: Use --exclude to trim unused vendors:
```
burgomaster create my-package.phar --exclude=vendor/doctrine/*
```
Debugging
- Issue: Stack traces in PHARs point to phar:// paths, making debugging harder.
- Fix: Use --verbose to inspect contents and log PHAR paths:
```
burgomaster create my-package.phar --verbose
```

Debugging Tips

Inspect PHAR Contents List files in a PHAR:
```
phar -l my-package.phar
```
Test PHAR Locally Run the PHAR with php -d phar.readonly=0:
```
php -d phar.readonly=0 my-package.phar
```

Validate Signatures Check PHAR signatures:

burgomaster validate my-package.phar --public-key=key.pub

Extension Points

Custom Stubs Override the default PHAR stub by passing a file:
```
burgomaster create my-package.phar --stub=custom-stub.txt
```
Pre/Post-Package Scripts Hook into Composer scripts to extend Burgomaster:
```
"scripts": {
    "post-package": "php artisan optimize"
}
```

Streaming to S3 Pipe PHARs directly to cloud storage:

$burgomaster->package('src/', null, ['stream' => true])
    ->pipeTo(fopen('s3://my-bucket/my-package.phar', 'w'));

Laravel-Specific Quirks

Artisan Commands in PHARs

Issue: PHARs cannot use Laravel’s service container directly.

Fix: Use a minimal stub to bootstrap the command:

// stub.txt
<?php
Phar::mapPhar('my-command.phar');
require 'phar://my-command.phar/vendor/autoload.php';
$command = new \MyNamespace\MyCommand();
$command->handle();

PHARs and OPCache
- Tip: Enable OPCache for PHARs to improve performance:
```
; php.ini
opcache.enable=1
opcache.enable_file_override=1
```
Environment-Specific Packaging
- Tip: Use --env to package different configs for dev/prod:
```
burgomaster create my-package-prod.phar --include=config/production.php
```

Burgomaster Laravel Package