Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dzignphp/core-bundle
   

   Add to config/app.php under extra.bundles:

   Dzignphp\CoreBundle\DzignphpCoreBundle::class => ['all' => true],
   

2. First Use Case

   • Dependency Injection: Use the bundle’s base services (e.g., Dzignphp\CoreBundle\Service\BaseService) as a foundation for your own services.
   • Configuration: Check config/packages/dzignphp_core.yaml for default settings (if provided) and override in your project’s config.

3. Where to Look First

   • Services: Explore src/Service/ for reusable logic (e.g., logging, validation, or utility helpers).
   • Traits: Check src/Traits/ for shared behavior (e.g., HasLoggerTrait).
   • Commands: Review src/Command/ for CLI tools (if available).
   • Tests: Study tests/ for usage examples and edge cases.

Implementation Patterns

Core Workflows

1. Extending Base Services

   • Inherit from BaseService to leverage built-in methods like log(), validate(), or handleException().
   • Example:

     use Dzignphp\CoreBundle\Service\BaseService;
     
     class MyCustomService extends BaseService {
         public function doSomething() {
             $this->log('Action triggered');
             // Custom logic here
         }
     }
     

2. Configuration-Driven Features

   • Use YAML/ENV config (e.g., dzignphp_core.enabled_features) to toggle bundle features dynamically.
   • Example in config/packages/dzignphp_core.yaml:

     dzignphp_core:
         enabled_features: [logging, validation]
     

3. Event Listeners/Subscribers

   • Attach listeners to bundle events (if documented) via EventDispatcher.
   • Example:

     use Dzignphp\CoreBundle\Event\MyEvent;
     
     class MyListener implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 MyEvent::class => 'onMyEvent',
             ];
         }
         public function onMyEvent(MyEvent $event) { ... }
     }
     

4. CLI Integration

   • Register custom commands in src/Command/ and bind them to the container.
   • Example:

     namespace App\Command;
     
     use Dzignphp\CoreBundle\Command\BaseCommand;
     
     class MyCommand extends BaseCommand {
         protected function configure() {
             $this->setName('app:my-command');
         }
         protected function execute(InputInterface $input, OutputInterface $output) {
             $this->log('Command executed');
         }
     }
     

Integration Tips

• Leverage Traits: Prefer traits over abstract classes for lightweight reuse (e.g., HasLoggerTrait).
• Service Binding: Override default services in config/services.yaml:

  services:
      Dzignphp\CoreBundle\Service\BaseService: '@app.custom_base_service'
  

• Middleware: If the bundle provides middleware, extend it in kernel.php:

  $kernel->pushMiddleware(new \Dzignphp\CoreBundle\HttpMiddleware\MyMiddleware());
  

Gotchas and Tips

Pitfalls

1. Undocumented Features

   • The bundle lacks stars/tests, so assume minimal documentation. Explore source code for undocumented methods/traits.
   • Example: A BaseService might have hidden debug() or cache() methods not mentioned in the README.

2. Configuration Overrides

   • If dzignphp_core.yaml is missing, the bundle may use hardcoded defaults. Always check for config files in:
     • config/packages/dzignphp_core.yaml
     • config/dzignphp_core.yaml (fallback).

3. Namespace Collisions

   • The bundle uses Dzignphp (with a "z"), not Design or similar. Double-check imports to avoid ClassNotFound errors.

4. Event System Assumptions

   • If the bundle emits events (e.g., KernelEvents::REQUEST), ensure your listeners are registered after the bundle’s subscribers.

5. Performance Overhead

   • Traits like HasLoggerTrait may add logging to every method call. Disable via config if unused:

     dzignphp_core:
         logging:
             enabled: false
     

Debugging Tips

• Enable Debug Mode: Set APP_DEBUG=true in .env to see detailed logs from BaseService::log().
• Service Dumping: Use Symfony’s debug:container to inspect bound services:

  php bin/console debug:container Dzignphp\CoreBundle
  

• Event Debugging: List all subscribed events:

  php bin/console debug:event-dispatcher
  

Extension Points

1. Custom Traits

   • Extend existing traits (e.g., HasLoggerTrait) by creating your own:

     trait MyCustomLoggerTrait {
         use HasLoggerTrait {
             HasLoggerTrait::log as private parentLog;
         }
         public function log(string $message) {
             $this->parentLog("[CUSTOM] {$message}");
         }
     }
     

2. Service Decorators

   • Decorate BaseService to modify behavior:

     services:
         app.base_service.decorated:
             decorates: 'dzignphp_core.base_service'
             arguments: ['@app.base_service.decorated.inner']
     

3. Command Extensions

   • Override bundle commands by redefining them in your Command/ directory with higher priority.

4. Compiler Passes

   • If the bundle uses compiler passes (e.g., for service modification), extend them in your own pass:

     use Dzignphp\CoreBundle\DependencyInjection\Compiler\MyPass;
     
     class MyCustomPass extends MyPass {
         public function process(ContainerBuilder $container) {
             // Extend logic here
         }
     }
     

     Register it in services.yaml:

     services:
         app.my_custom_pass:
             tags: [compiler]
             arguments: ['@service_container']