Getting Started

Minimal Setup

Installation

composer require yfix/packager

Add to composer.json under require-dev if only needed for local builds:

"require-dev": {
    "yfix/packager": "^1.0"
}

Basic Usage Create a package.yml file in your project root (MooTools-style syntax):

name: my-package
version: 1.0.0
description: "A Laravel package built with Packager"
files:
    - src/
    - composer.json
    - README.md

First Build Run the build command:
```
php artisan packager:build
```
Outputs a .zip file in storage/app/packages/ (default).

Where to Look First

Configuration: config/packager.php (if published via php artisan vendor:publish).
CLI Commands: php artisan packager:build (core command).
Service Provider: Yfix\Packager\PackagerServiceProvider (registers commands).

First Use Case: Packaging a Laravel Package

Define package.yml with your package structure.
Run php artisan packager:build.
Use the generated .zip for distribution (e.g., Packagist, GitHub Releases).

Implementation Patterns

Workflow Integration

CI/CD Pipeline Add to .github/workflows/build.yml:
```
- name: Build Package
  run: php artisan packager:build
```
Upload the generated .zip as an artifact.
Local Development Use php artisan packager:build --watch for auto-rebuilding on file changes.

Custom Build Steps Extend the builder via events:

// In a service provider
event(new \Yfix\Packager\Events\PreBuild());

Common Patterns

Pattern	Example
Excluding Files	Add `exclude: [node_modules/, .env]` to `package.yml`.
Custom Output Path	Set in `config/packager.php`: `'output_path' => 'custom/path'`.
Versioning	Use `{{ version }}` in filenames (e.g., `my-package-{{ version }}.zip`).
Post-Build Hooks	Listen for `\Yfix\Packager\Events\PostBuild` to run scripts.

Laravel-Specific Tips

Publish Config:

php artisan vendor:publish --provider="Yfix\Packager\PackagerServiceProvider"

Service Provider Binding: Bind the Packager facade in AppServiceProvider:

$this->app->bind('packager', function ($app) {
    return new \Yfix\Packager\Packager();
});

Testing: Use php artisan packager:build --test to validate package.yml syntax.

Gotchas and Tips

Pitfalls

YAML Syntax Errors
- Symptom: Build fails silently or ignores package.yml.
- Fix: Validate YAML with php artisan packager:validate.
File Permissions
- Symptom: .zip file not generated in storage/app/packages/.
- Fix: Ensure storage/ is writable:
```
chmod -R 775 storage/
```
Version Placeholders
- Symptom: {{ version }} not replaced in filenames.
- Fix: Ensure composer.json has a valid version field.
Case Sensitivity
- Symptom: Files not included despite correct paths in package.yml.
- Fix: Use absolute paths or verify case sensitivity in files: section.

Debugging Tips

Verbose Output:
```
php artisan packager:build -v
```
Dry Run:
```
php artisan packager:build --dry-run
```
Lists files to be included without creating a .zip.
Log Events: Enable logging in config/packager.php:
```
'debug' => env('PACKAGER_DEBUG', false),
```

Extension Points

Custom Builders Implement Yfix\Packager\Contracts\Builder:

class CustomBuilder implements Builder {
    public function build(array $config) { ... }
}

'builder' => \App\Services\CustomBuilder::class,

Pre/Post Build Events Listen globally in EventServiceProvider:

protected $listen = [
    \Yfix\Packager\Events\PreBuild::class => [
        \App\Listeners\ValidatePackage::class,
    ],
];

Override Defaults Extend Yfix\Packager\Packager class and bind it in AppServiceProvider:

$this->app->singleton('packager', function () {
    return new \App\Services\CustomPackager();
});

Config Quirks

Output Path: Defaults to storage/app/packages/. Change via:
```
'output_path' => storage_path('custom-packages'),
```
Zip Compression: Disable with 'compress' => false in config (outputs a .tar instead).
Excludes: Glob patterns (e.g., tests/*) are supported but may not work as expected on all systems. Test locally.

Pro Tips

Template Files Use package.yml templates with extends:
```
extends: base-package.yml
files:
    - src/
```
(Requires custom builder implementation.)

Git Integration Auto-generate CHANGELOG.md by hooking into PostBuild:

public function handle(PostBuild $event) {
    $this->generateChangelog($event->packagePath);
}

Multi-Package Projects Use --package flag to build specific packages:
```
php artisan packager:build --package="admin-panel"
```
(Requires named package.yml files like admin-panel.yml.)

Packager Laravel Package