Packager Laravel Package

Getting Started

Minimal Steps to First Use

1. Install Globally:

   composer global require laravel-ready/packager --dev
   

   Ensure ~/.composer/vendor/bin is in your PATH.

2. Initialize a New Package:

   mkdir my-package && cd my-package
   git init
   composer init --type=project --name=vendor/package-name --description="My Awesome Package"
   packager new
   

   Follow prompts for package metadata (name, author, description, etc.).

3. First Use Case:

   • Run php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider" to publish stubs (config, migrations, etc.).
   • Test the package in a Laravel app by requiring it via composer require vendor/package-name.

Implementation Patterns

Workflows

1. Template-Based Generation:

   • Packager auto-generates:
     • src/ (PSR-4 compliant classes).
     • config/ (publishable config files).
     • database/migrations/ (if migrations are enabled).
     • resources/views/ (if views are enabled).
     • tests/ (PHPUnit test boilerplate).
   • Customize templates by overriding packager:templates config or extending the PackagerServiceProvider.

2. Integration with Laravel:

   • Service Providers: Register the package’s bindings in PackageServiceProvider (auto-generated).
   • Facades: Use php artisan make:facade for package-specific facades.
   • Commands: Extend PackagerCommand or create custom Artisan commands in src/Console.

3. Versioning and Releases:

   • Use packager:release to generate changelogs and version tags (if configured).
   • Integrate with GitHub/GitLab Actions for automated releases.

4. Testing:

   • Run php artisan test (PHPUnit) with pre-configured test classes.
   • Mock Laravel dependencies using createApplication() in tests (see tests/TestCase.php).

Integration Tips

• Composer Scripts: Add to composer.json:

  "scripts": {
    "post-autoload-dump": "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
    "post-update-cmd": "php artisan package:discover"
  }
  

• Laravel Packages: For multi-package projects, use packager:install to scaffold dependencies.
• CI/CD: Configure GitHub Actions to run packager test and packager lint in workflows.

Gotchas and Tips

Pitfalls

1. Template Overrides:

   • If custom templates are placed in templates/ (e.g., resources/templates/), ensure they match Packager’s expected structure. Misplaced files may break generation.
   • Fix: Run php artisan packager:clear-cache after template changes.

2. Namespace Conflicts:

   • Packager auto-generates namespaces based on composer.json. Mismatched namespaces in src/ or tests/ will cause autoloading errors.
   • Fix: Verify autoload.psr-4 in composer.json matches the src/ directory structure.

3. Laravel Version Mismatch:

   • Packager defaults to Laravel 9.x. For older/new versions, override the laravel_version in packager.json or use --laravel-version flag.
   • Fix: Check vendor/laravel/framework compatibility in your package’s composer.json.

4. Published Assets:

   • Forgetting to publish config/migrations/views can lead to runtime errors.
   • Fix: Always run php artisan vendor:publish --tag=package-config (or relevant tag) after installation.

5. Global Composer Cache:

   • If packager new fails, clear Composer’s global cache:

     composer global clear-cache
     

Debugging

• Verbose Mode: Run packager new --verbose to debug template rendering issues.
• Logs: Check storage/logs/laravel.log for Packager-related errors during generation.
• Dry Runs: Use packager new --dry-run to preview changes without writing files.

Extension Points

1. Custom Templates:

   • Override default templates by creating a templates/ directory in your package root.
   • Example: Copy vendor/laravel-ready/packager/templates/src/ServiceProvider.stub to templates/src/.

2. Hooks:

   • Extend PackagerServiceProvider to add post-generation tasks:

     public function boot()
     {
         $this->afterPackageGenerated(function () {
             // Add custom logic (e.g., git init, run migrations)
         });
     }
     

3. Configuration:

   • Customize generation via packager.json:

     {
       "enable_migrations": false,
       "enable_tests": true,
       "enable_views": true
     }
     

   • Override via CLI:

     packager new --enable-tests --disable-migrations
     

4. Multi-Package Projects:

   • Use packager:install with --package flag to scaffold dependent packages:

     packager install vendor/dependent-package --package