Bundle Skeleton Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require blast-project/bundle-skeleton
   

   Note: This package is deprecated, so verify compatibility with your Laravel version (likely 5.x).

2. Bundle Initialization

   • Locate the BundleServiceProvider in vendor/blast-project/bundle-skeleton/src/.
   • Register it in config/app.php under providers:

     'providers' => [
         // ...
         BlastProject\BundleSkeleton\BundleServiceProvider::class,
     ],
     

3. First Use Case: Creating a Basic Bundle

   • Copy the src/ directory structure to your project (e.g., app/Bundles/MyBundle/).
   • Replace namespace placeholders (BlastProject\BundleSkeleton) with your bundle’s namespace.
   • Publish the skeleton’s assets (if applicable) via:

     php artisan vendor:publish --provider="BlastProject\BundleSkeleton\BundleServiceProvider" --tag="config"
     

Implementation Patterns

Core Workflow: Bundle Development

1. Namespace Isolation

   • Use the skeleton’s BundleServiceProvider as a template to enforce PSR-4 autoloading for your bundle:

     // app/Bundles/MyBundle/MyBundleServiceProvider.php
     namespace App\Bundles\MyBundle;
     
     class MyBundleServiceProvider extends \BlastProject\BundleSkeleton\BundleServiceProvider {
         protected $namespace = 'App\Bundles\MyBundle';
     }
     

2. Service Registration

   • Extend the skeleton’s register() method to bind facades, services, or macros:

     public function register() {
         $this->app->singleton('my-bundle.service', function ($app) {
             return new MyService();
         });
     }
     

3. Configuration Management

   • Publish and merge config files:

     php artisan vendor:publish --provider="App\Bundles\MyBundle\MyBundleServiceProvider" --tag="config"
     

   • Use the skeleton’s config() method to load defaults:

     protected function config() {
         $this->publishes([
             __DIR__.'/config/my-bundle.php' => config_path('my-bundle.php'),
         ], 'config');
     }
     

4. Asset Handling

   • For views/assets, leverage Laravel’s publishes method:

     public function boot() {
         $this->loadViewsFrom(__DIR__.'/views', 'my-bundle');
         $this->publishes([
             __DIR__.'/public' => public_path('vendor/my-bundle'),
         ], 'public');
     }
     

5. Command Integration

   • Add custom Artisan commands by extending Illuminate\Console\Command in your bundle’s Console directory.

Integration Tips

• Dependency Injection: Use the skeleton’s service container bindings to inject dependencies into controllers/services.
• Event Handling: Subscribe to Laravel events in boot():

  public function boot() {
      event(new MyBundleEvent());
  }
  

• Middleware: Register middleware via RouteServiceProvider or directly in boot():

  $this->app['router']->aliasMiddleware('my-bundle', \App\Bundles\MyBundle\Http\Middleware\MyMiddleware::class);
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning

   • The package is marked as deprecated. Audit for Laravel 5.x compatibility issues (e.g., RouteServiceProvider changes in Laravel 5.3+).
   • Workaround: Fork the repo and update dependencies manually if needed.

2. Namespace Collisions

   • The skeleton uses BlastProject\BundleSkeleton as a root namespace. Ensure your bundle’s namespace doesn’t conflict with existing code.
   • Tip: Use a unique vendor prefix (e.g., Acme\Bundles\MyBundle).

3. Missing Documentation

   • Lack of a changelog or detailed README may obscure advanced features.
   • Tip: Inspect the src/ directory for undocumented patterns (e.g., BundleServiceProvider methods).

4. Asset Publishing Quirks

   • The skeleton assumes a public/ directory in the bundle root. Customize paths in boot() if your structure differs.
   • Example Fix:

     $this->publishes([
         __DIR__.'/resources/assets' => public_path('bundles/my-bundle'),
     ], 'public');
     

5. Service Provider Boot Order

   • If your bundle depends on other services, ensure its ServiceProvider is registered after dependencies in config/app.php.

Debugging Tips

1. Service Binding Issues

   • Verify bindings in register() are correct:

     php artisan config:clear
     php artisan cache:clear
     

   • Check for duplicate bindings with:

     dd($this->app->bound('my-service')); // Should return true
     

2. Configuration Overrides

   • Debug config merging by dumping the final config:

     dd(config('my-bundle'));
     

3. Route/Asset Paths

   • Use Laravel’s asset() helper with explicit paths:

     <link href="{{ asset('vendor/my-bundle/css/style.css') }}" rel="stylesheet">
     

Extension Points

1. Custom Facades

   • Extend the skeleton’s facade pattern:

     // app/Bundles/MyBundle/Facades/MyFacade.php
     namespace App\Bundles\MyBundle\Facades;
     
     use Illuminate\Support\Facades\Facade;
     
     class MyFacade extends Facade {
         protected static function getFacadeAccessor() { return 'my-bundle.service'; }
     }
     

   • Register the facade in register():

     $this->app->bind('my-facade', function () {
         return new MyFacade();
     });
     

2. Dynamic Configuration

   • Load environment-specific configs in boot():

     $this->mergeConfigFrom(__DIR__.'/config/my-bundle-'.config('app.env').'.php', 'my-bundle');
     

3. Testing Hooks

   • Add testable service providers by extending Illuminate\Foundation\Testing\Concerns\InteractsWithServiceProviders:

     use App\Bundles\MyBundle\MyBundleServiceProvider;
     
     class MyBundleTestCase extends TestCase {
         public function setUp(): void {
             parent::setUp();
             $this->withServiceProviders([MyBundleServiceProvider::class]);
         }
     }