Laravel Package Tpl Laravel Package

Getting Started

Minimal Steps to Begin

1. Install via Composer Template Use the template to scaffold a new package:

   composer create-project wayofdev/laravel-package-tpl my-package-name
   

   • Navigate into the project directory:

     cd my-package-name
     

2. Configure Package Metadata Edit composer.json to update:

   • name (e.g., vendor/package-name)
   • description
   • authors
   • require (Laravel version constraints, e.g., ^10.0)

3. Set Up Environment Copy .env.example to .env and configure:

   cp .env.example .env
   

   • Update APP_NAME, APP_URL, and other environment variables.

4. Run Initial Setup Install dependencies and generate keys:

   composer install
   php artisan key:generate
   

5. First Use Case: Publish a Service Provider

   • Register a service provider in config/app.php (or dynamically via PackageServiceProvider).
   • Example:

     // config/app.php
     'providers' => [
         WayOfDev\MyPackage\Providers\PackageServiceProvider::class,
     ],
     

Implementation Patterns

Core Workflows

1. Service Provider Integration

   • Extend Illuminate\Support\ServiceProvider in app/Providers/PackageServiceProvider.php.
   • Bind facades, services, and macros:

     public function register()
     {
         $this->app->singleton(MyService::class, fn () => new MyService());
         $this->app->bind('my-package', fn () => $this->app->make(MyService::class));
     }
     

2. Publishing Assets/Config

   • Use publishes in PackageServiceProvider:

     if ($this->app->runningInConsole()) {
         $this->publishes([
             __DIR__.'/../config/my-package.php' => config_path('my-package.php'),
         ], 'my-package-config');
     }
     

   • Publish via Artisan:

     php artisan vendor:publish --provider="WayOfDev\MyPackage\Providers\PackageServiceProvider" --tag="my-package-config"
     

3. Artisan Commands

   • Place commands in app/Console/Commands.
   • Register in PackageServiceProvider:

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

   • Example command:

     php artisan my:command --option=value
     

4. Testing with PHPUnit

   • Run tests:

     ./vendor/bin/phpunit
     

   • Mock Laravel services in tests/TestCase.php:

     public function setUp(): void
     {
         parent::setUp();
         $this->app->instance('my-service', Mockery::mock(MyService::class));
     }
     

5. Docker Integration

   • Use docker-compose.yml for local development.
   • Spin up services:

     docker-compose up -d
     

   • Access the container:

     docker-compose exec app bash
     

Integration Tips

1. Leverage Laravel’s Package Discovery

   • Ensure composer.json includes:

     "extra": {
         "laravel": {
             "providers": ["WayOfDev\\MyPackage\\Providers\\PackageServiceProvider"],
             "aliases": {
                 "MyPackage": "WayOfDev\\MyPackage\\Facades\\MyPackage"
             }
         }
     }
     

   • No need to manually register providers in config/app.php.

2. Dynamic Configuration

   • Use config() helper with a fallback:

     $value = config('my-package.key', 'default');
     

3. Event Listeners

   • Register listeners in PackageServiceProvider:

     Event::listen(MyEvent::class, MyListener::class);
     

   • Dispatch events:

     event(new MyEvent($data));
     

4. Blade Directives

   • Register directives in PackageServiceProvider:

     Blade::directive('myDirective', function ($expression) {
         return "<?php echo customLogic($expression); ?>";
     });
     

5. API Resources

   • Extend Illuminate\Http\Resources\Json\JsonResource in app/Http/Resources.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Ensure all classes use consistent namespaces (e.g., WayOfDev\MyPackage\...).
   • Avoid collisions with Laravel core or other packages.

2. Autoloading Issues

   • Run composer dump-autoload after adding new classes.
   • Verify autoload in composer.json:

     "autoload": {
         "psr-4": {
             "WayOfDev\\MyPackage\\": "app/"
         }
     }
     

3. Service Provider Boot Order

   • Laravel boots providers alphabetically. Use priority in register() for critical dependencies:

     $this->app->register(AnotherServiceProvider::class, ['priority' => 10]);
     

4. Testing Pitfalls

   • Mock Laravel’s App facade or services in tests to avoid side effects:

     $this->app->instance('app', Mockery::mock('overload:App'));
     

   • Use RefreshDatabase trait for database tests:

     use Illuminate\Foundation\Testing\RefreshDatabase;
     

5. Docker Volumes

   • Ensure docker-compose.yml mounts the correct volumes for live-reload:

     volumes:
         - ./:/var/www/html
     

Debugging

1. Log Output

   • Use Laravel’s log channels:

     \Log::debug('Debug message', ['context' => 'key']);
     

   • Check logs at storage/logs/laravel.log.

2. Xdebug in Docker

   • Add to docker-compose.yml:

     services:
         app:
             extra_hosts:
                 - "host.docker.internal:host-gateway"
     

   • Configure php.ini for Xdebug:

     xdebug.mode=debug
     xdebug.start_with_request=yes
     

3. Artisan Command Debugging

   • Use --verbose flag:

     php artisan my:command --verbose
     

Extension Points

1. Custom GitHub Actions

   • Extend .github/workflows/ with additional workflows (e.g., for deployment).

2. PHPStan Rules

   • Add custom rules in phpstan.neon:

   includes:
       - vendor/wayofdev/laravel-package-tpl/phpstan/
   

3. Docker Compose Overrides

   • Use docker-compose.override.yml for environment-specific configs.

4. Laravel Mix/Webpack

   • Customize webpack.mix.js for frontend assets (if applicable).

5. Package Bootstrap

   • Override bootstrap/app.php for global package initialization:

     $app->register(\WayOfDev\MyPackage\Providers\PackageServiceProvider::class);