Laravel Packager Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require --dev jeroen-g/laravel-packager
   

   Run the publisher to set up config (if needed):

   php artisan vendor:publish --provider="JeroenG\LaravelPackager\PackagerServiceProvider"
   

2. First Use Case: Scaffold a New Package

   php artisan package:make MyPackage
   

   This generates a boilerplate package structure in packages/MyPackage/ with:

   • composer.json
   • src/ (core logic)
   • tests/ (PHPUnit)
   • config/ (publishable config)
   • resources/ (views, lang, etc.)
   • README.md

3. Key Files to Review First

   • packages/MyPackage/composer.json: Define package metadata, autoloading, and Laravel-specific keys like extra.laravel.
   • packages/MyPackage/src/MyPackageServiceProvider.php: Register package services, bindings, and migrations.
   • packages/MyPackage/config/package.php: Default config (published via php artisan vendor:publish).

Implementation Patterns

Core Workflows

1. Package Development Loop

• Develop Locally: Use composer require ./packages/MyPackage to link the package in your Laravel app.

  composer require ./packages/MyPackage --dev
  

• Test Incrementally: Run tests with:

  php artisan test --filter=MyPackageTest
  

• Publish Assets/Config:

  php artisan vendor:publish --provider="MyPackage\MyPackageServiceProvider" --tag="config"
  php artisan vendor:publish --provider="MyPackage\MyPackageServiceProvider" --tag="migrations"
  

2. Integration with Laravel Features

• Service Providers: Extend the package’s MyPackageServiceProvider to bind facades, commands, or events:

  public function boot()
  {
      $this->loadViewsFrom(__DIR__.'/../resources/views', 'my-package');
      $this->publishes([__DIR__.'/../config/package.php' => config_path('package.php')], 'config');
  }
  

• Commands: Scaffold a command with:

  php artisan package:make-command MyCommand --package=MyPackage
  

  Register it in MyPackageServiceProvider:

  $this->commands([MyCommand::class]);
  

3. Versioning and Releases

• Tagging Releases: Use semantic versioning in composer.json (e.g., "version": "1.0.0"). Tag releases with:

  git tag v1.0.0
  git push origin v1.0.0
  

• Packagist Submission: Ensure composer.json has:

  "require": {
      "php": "^8.0",
      "laravel/framework": "^9.0"
  },
  "extra": {
      "laravel": {
          "providers": ["MyPackage\\MyPackageServiceProvider"]
      }
  }
  

  Submit to Packagist manually or via GitHub Actions.

Advanced Patterns

1. Dynamic Package Configuration

Use Laravel’s config system to make settings dynamic:

// In MyPackageServiceProvider::boot()
config(['package.default_setting' => env('PACKAGE_DEFAULT_SETTING', 'default')]);

Publish the config file and override via .env:

PACKAGE_DEFAULT_SETTING=custom_value

2. Package Discovery

For Laravel 5.5+, ensure composer.json includes:

"extra": {
    "laravel": {
        "discover": true
    }
}

This auto-loads the service provider without manual registration.

3. Testing Packages

Use Laravel’s testing helpers in tests/Feature/:

public function test_package_functionality()
{
    $response = $this->get('/my-package/endpoint');
    $response->assertStatus(200);
}

Mock dependencies with Laravel’s Mockery or createMock().

4. Asset Compilation

For frontend assets (e.g., JavaScript/CSS), use Laravel Mix or Vite:

// resources/js/package.js
window.MyPackage = { /* ... */ };

Compile with:

npm run dev

Publish assets via publishes in the service provider:

$this->publishes([
    __DIR__.'/../resources/js/dist/package.js' => public_path('vendor/my-package/package.js'),
], 'assets');

Gotchas and Tips

Common Pitfalls

1. Autoloading Issues

• Symptom: Classes not found after composer dump-autoload.
• Fix: Ensure composer.json has correct autoload paths:

  "autoload": {
      "psr-4": {
          "MyPackage\\": "src/"
      }
  }
  

  Run:

  composer dump-autoload
  

2. Service Provider Not Registering

• Symptom: Package features (e.g., facades) unavailable.
• Debug: Check if the provider is listed in config/app.php under providers. For Laravel 5.5+, ensure "discover": true is set in extra.laravel.

3. Published Config Overrides

• Symptom: Config changes not reflected after publishing.
• Fix: Clear config cache:

  php artisan config:clear
  

  Or manually merge config in MyPackageServiceProvider::boot():

  $this->mergeConfigFrom(__DIR__.'/../config/package.php', 'package');
  

4. Namespace Conflicts

• Symptom: Class name collisions with host Laravel app.
• Solution: Use unique namespaces (e.g., Vendor\PackageName\...) and avoid App or Laravel prefixes.

5. Testing Environment Quirks

• Symptom: Tests pass locally but fail on CI (e.g., GitHub Actions).
• Fix: Ensure .env.testing is configured for CI:

  APP_ENV=testing
  DB_CONNECTION=sqlite_memory
  

  Use php artisan test --env=testing to debug.

Debugging Tips

1. Log Package Events

Add debug logs in MyPackageServiceProvider:

public function boot()
{
    \Log::info('MyPackage initialized');
}

Check logs with:

tail -f storage/logs/laravel.log

2. Dump Service Container

Inspect bindings:

\Log::info('Container bindings:', [
    'my_package_binding' => app()->bound('my.package.binding') ? app('my.package.binding') : 'Not bound'
]);

3. Verify Composer Scripts

Ensure composer.json scripts run correctly:

"scripts": {
    "post-autoload-dump": [
        "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
        "@php artisan package:discover"
    ]
}

Extension Points

1. Custom Commands

Extend the package’s CLI with:

php artisan package:make-command MyCustomCommand --package=MyPackage

Example: Add a package:generate-key command for API tokens.

2. Dynamic Package Loading

Use Laravel’s PackageDiscovery to load packages conditionally:

// In a custom service provider
if ($this->app->environment('local')) {
    $this->loadPackage('MyPackage\\LocalPackageServiceProvider');
}

3. Package Dependencies

Define dependencies in composer.json:

"require": {
    "laravel/framework": "^9.0",
    "spatie/laravel-package-tools": "^1.0" // Example dependency
}

4. Hooks for Laravel Events

Listen to Laravel events in MyPackageServiceProvider:

public function boot()
{
    event(new \MyPackage\Events\PackageInitialized());
}

Dispatch events from package logic:

event(new \MyPackage\Events\TaskCompleted($task));

5. API Resources

For API packages, use Laravel’s ApiResource:

namespace MyPackage\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class MyResource extends JsonResource
{