Getting Started

Installation Add the package via Composer:
```
composer require humbug/box --dev
```
No additional configuration is required—Box is designed to be zero-config.
Basic Usage Run the following command in your Laravel project root to generate a PHAR:
```
vendor/bin/box compile
```
This creates a public/box.phar file containing your application and dependencies.
First Use Case: Deployment Use Box to bundle your Laravel app for deployment (e.g., shared hosting without Composer):
```
vendor/bin/box compile --output=public/app.phar
```
Upload app.phar to your server and execute it via:
```
php public/app.phar
```

Implementation Patterns

Bundling for Production Exclude unnecessary files (e.g., .env, node_modules) via .boxignore:
```
.env
node_modules/
storage/logs/
```
Compile with:
```
vendor/bin/box compile --output=public/app.prod.phar
```
Custom Entry Points Override the default index.php by specifying a custom entry file:
```
vendor/bin/box compile --entry=public/custom-entry.php
```
Including External Files Add non-PHP assets (e.g., fonts, images) via --include:
```
vendor/bin/box compile --include=public/assets/fonts/
```
Integration with Laravel Mix Use Box alongside Laravel Mix for frontend assets:
```
npm run dev && vendor/bin/box compile --output=public/app.phar
```

Automating with CI/CD Add Box to your GitHub Actions workflow:

- name: Build PHAR
  run: vendor/bin/box compile --output=public/app.phar

Multi-PHAR Deployments Bundle different environments (e.g., app.dev.phar, app.staging.phar) with environment-specific configs.
PHAR as a CLI Tool Use --bin to expose a custom CLI command:
```
vendor/bin/box compile --bin=app:command=MyCommand
```
Access via php app.phar my:command.

Missing Dependencies Ensure all required Composer packages are installed before compiling:
```
composer install --optimize-autoloader
```
Box does not auto-resolve missing dependencies.
Class Loading Issues If autoloading fails, regenerate the Composer autoloader:
```
composer dump-autoload
```
File Permissions PHARs require executable permissions on the server:
```
chmod +x public/app.phar
```
Environment Variables .env files are ignored by default. Use --env to embed them:
```
vendor/bin/box compile --env=.env.production
```
Large PHAR Sizes Exclude unused dependencies or files to reduce size. Use --exclude:
```
vendor/bin/box compile --exclude=vendor/doctrine/*
```

Verify PHAR Contents List files in the PHAR:

php -r "print_r(Box\Phar::getFiles('public/app.phar'));"

Check for Errors Run with --verbose for detailed logs:
```
vendor/bin/box compile --verbose
```
Test Locally Use --test to validate the PHAR before deployment:
```
vendor/bin/box compile --test
```

Custom Build Scripts Extend Box with a box.json config file:

{
  "entry": "public/index.php",
  "includes": ["public/assets/"],
  "excludes": ["vendor/monolog/*"]
}

Post-Compile Hooks Use post-compile scripts in package.json or composer.json:
```
{
  "scripts": {
    "post-box": "php artisan optimize"
  }
}
```
PHAR-Specific Logic Detect if running inside a PHAR in your Laravel code:
```
if (Phar::running()) {
    // Custom logic for PHAR execution
}
```