Common Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require edlcdmc/common-bundle
   

   Register the bundle in config/app.php under ExtraBundles (if using Symfony/Laravel-Symfony hybrid) or manually bootstrap via composer.json autoload.

2. First Use Case Check the src/Resources/config/services.yml for default configurations. If the bundle provides a service (e.g., common.service), bind it in Laravel’s config/services.php:

   'common' => [
       'default' => env('COMMON_SERVICE', 'common.service'),
   ],
   

   Then resolve it in a controller:

   use Illuminate\Support\Facades\Config;
   $service = app()->make(Config::get('services.common.default'));
   

3. Where to Look First

   • src/: Core logic (services, utilities).
   • Resources/config/: Default configurations (override via Laravel’s config/).
   • README.md: Check for undocumented features (e.g., CLI commands, event listeners).

Implementation Patterns

Core Workflows

1. Service Integration If the bundle provides a CommonService, extend it or wrap it in a Laravel service provider:

   // app/Providers/CommonServiceProvider.php
   public function register()
   {
       $this->app->singleton('common', function ($app) {
           return new \Edlcdmc\CommonBundle\Service\CommonService(
               $app['config']['common.settings']
           );
       });
   }
   

2. Configuration Overrides Publish and override default configs:

   php artisan vendor:publish --provider="Edlcdmc\CommonBundle\CommonBundle"
   

   Then customize config/common.php.

3. Event Listeners If the bundle dispatches events (e.g., CommonEvent), listen in Laravel’s EventServiceProvider:

   protected $listen = [
       \Edlcdmc\CommonBundle\Event\CommonEvent::class => [
           \App\Listeners\HandleCommonEvent::class,
       ],
   ];
   

4. CLI Commands Register bundle commands in app/Console/Kernel.php:

   protected $commands = [
       \Edlcdmc\CommonBundle\Command\CommonCommand::class,
   ];
   

Laravel-Specific Tips

• Service Container: Prefer Laravel’s DI over Symfony’s container (e.g., avoid $container->get(); use app()->make()).
• Blade Integration: If the bundle provides helpers, create a Blade directive:

  // app/Providers/BladeServiceProvider.php
  Blade::directive('commonHelper', function ($expr) {
      return "<?php echo app('common')->{$expr}; ?>";
  });
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions The bundle may use Edlcdmc\CommonBundle\* namespaces. Ensure no conflicts with your app’s app/ namespace.

2. Symfony vs. Laravel Quirks

   • Dependency Injection: The bundle may assume Symfony’s container. Mock dependencies explicitly:

     $service = $this->app->makeWith(\Edlcdmc\CommonBundle\Service\CommonService::class, [
         'config' => $this->app['config']['common'],
     ]);
     

   • Routing: If the bundle registers routes, override them in routes.php or use middleware to intercept.

3. Configuration Merging Laravel’s config() merges arrays recursively. If the bundle expects a flat config, use:

   $config = array_merge(
       require __DIR__.'/common.php',
       $this->app['config']['common']
   );
   

4. Zero Stars/Maturity

   • No Tests: Assume undocumented edge cases. Test thoroughly.
   • No Dependents: Check for orphaned features (e.g., deprecated methods).

Debugging

• Enable Debugging: Set APP_DEBUG=true in .env to surface Symfony-style errors.
• Log Bundle Output: Wrap bundle calls in Laravel’s log:

  \Log::debug('CommonBundle output', ['data' => $service->execute()]);
  

Extension Points

1. Custom Services Extend core services via traits or inheritance:

   use Edlcdmc\CommonBundle\Service\CommonService as BaseService;
   
   class ExtendedCommonService extends BaseService {
       public function customMethod() { ... }
   }
   

2. Event Decorators Decorate bundle events to add Laravel-specific logic:

   $event->setUser(auth()->user()); // Inject Laravel auth
   

3. Command Extensions Override bundle commands by re-registering them in app/Console/Kernel.php:

   $this->commands = [
       \App\Console\Commands\CustomCommonCommand::class,
   ];