Laravel Package Skeleton Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Skeleton Globally Run:

   composer global require algoyounes/laravel-package-skeleton
   

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

2. Generate a New Package Use the scaffold command to create a new package:

   composer create-project algoyounes/laravel-package-skeleton your-package-name
   cd your-package-name
   

   Replace your-package-name with your desired package namespace (e.g., vendor/package-name).

3. First Use Case: Bootstrapping a Package

   • The skeleton generates a modular structure with:
     • src/ (Core logic)
     • config/ (Package config)
     • database/ (Migrations, seeders)
     • resources/ (Views, assets)
     • tests/ (Unit/Feature tests)
   • Run php artisan package:publish (if included) to publish assets/config.
   • Test locally with:

     composer test
     

Implementation Patterns

Core Workflows

1. Modular Development

   • Service Providers: Extend Illuminate\Support\ServiceProvider in src/YourPackageServiceProvider.php.

     public function register()
     {
         $this->app->bind('YourPackage\Contracts\YourContract', 'YourPackage\Services\YourService');
     }
     

   • Facades: Use php artisan package:facade to generate facades (if the skeleton includes this command). Example:

     // src/Facades/YourPackage.php
     public static function yourMethod() {
         return app('YourPackage')->yourMethod();
     }
     

2. Configuration Management

   • Publish config with:

     php artisan vendor:publish --provider="YourPackage\YourPackageServiceProvider" --tag="config"
     

   • Merge defaults in config/your-package.php:

     return [
         'option' => env('YOUR_PACKAGE_OPTION', 'default'),
     ];
     

3. Database Integration

   • Run migrations via:

     php artisan migrate --path=vendor/your-package-name/database/migrations
     

   • Use php artisan package:migrate (if included) for package-specific migrations.

4. Publishing Assets

   • Publish views/assets with:

     php artisan vendor:publish --provider="YourPackage\YourPackageServiceProvider" --tag="public"
     

   • Override in your app at resources/views/vendor/your-package/.

5. Testing

   • Run tests with:

     composer test
     

   • Use php artisan package:test (if available) for isolated package testing.

Integration Tips

• Dependency Injection: Prefer constructor injection for services.

  public function __construct(private YourService $service) {}
  

• Event Handling: Dispatch events in src/Events/ and listen in src/Listeners/.

  Event::dispatch(new YourPackageEvent($data));
  

• Commands: Extend Illuminate\Console\Command in src/Console/ and register in YourPackageServiceProvider.

  $this->commands([
      \YourPackage\Console\YourCommand::class,
  ]);
  

• API Resources: Use Laravel’s ApiResource for JSON responses (if applicable).

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Ensure your package’s namespace (e.g., YourPackage\) doesn’t conflict with the host app.
   • Use fully qualified names (e.g., \YourPackage\Services\YourService) in config/publishables.

2. Autoloading Issues

   • If classes aren’t autoloaded, run:

     composer dump-autoload
     

   • Verify composer.json includes:

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

3. Service Provider Registration

   • If the package isn’t discovered, manually add to config/app.php:

     'providers' => [
         YourPackage\YourPackageServiceProvider::class,
     ],
     

4. Migration Paths

   • Hardcoding migration paths (e.g., database/migrations) may fail in the host app. Use:

     $this->loadMigrationsFrom(__DIR__.'/../../../vendor/your-package-name/database/migrations');
     

5. Testing in Isolation

   • Mock the host app’s dependencies (e.g., Config, Filesystem) in tests:

     $this->app->instance('path', $mockPath);
     

Debugging Tips

• Log Package Events: Use Laravel’s log facade:

  \Log::debug('YourPackage event triggered', ['data' => $data]);
  

• Check Published Config: Verify config is merged correctly:

  dd(config('your-package.option'));
  

• Artisan Commands: Debug commands with:

  php artisan your:command --verbose
  

Extension Points

1. Custom Commands Add new commands in src/Console/ and register them in the service provider.

2. Dynamic Configuration Use config('your-package') in your package to access published settings.

3. Package Discovery Extend the skeleton to support Laravel Package Auto-Discovery (if needed):

   // In src/YourPackageServiceProvider.php
   public function boot()
   {
       $this->app->booted(function () {
           // Post-boot logic
       });
   }
   

4. Local Development Link the package locally for testing:

   composer config repositories.your-package-name path ./your-package-name
   composer require your-package-name/dev-main
   

5. Documentation Use Markdown in docs/ (if included) for API/usage docs. Generate with:

   php artisan package:docs