Base Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sidus/base-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Sidus\BaseBundle\SidusBaseBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Service Loading: Create a FooBarExtension extending SidusBaseExtension in DependencyInjection/:

     namespace AppBundle\DependencyInjection;
     use Sidus\BaseBundle\DependencyInjection\SidusBaseExtension;
     
     class FooBarExtension extends SidusBaseExtension {}
     

   • Place service definitions in Resources/config/services/*.yml (e.g., services/actions.yml):

     AppBundle\Action\MyAction: ~
     

   • Register the extension in Resources/config/services.xml:

     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://symfony.com/schema/dic/services
             http://symfony.com/schema/dic/services/services-1.0.xsd">
         <services>
             <extensions>
                 <extension class="AppBundle\DependencyInjection\FooBarExtension"/>
             </extensions>
         </services>
     </container>
     

3. Routing: Define routes in Resources/config/routing.yml:

   AppBundle_MyAction:
       path: /my-action/{id}
       defaults:
           _service: AppBundle\Action\MyAction
           _method: execute
   

Implementation Patterns

Service Declaration Workflow

1. Action-Based Controllers: Replace traditional controllers with service-based actions. Example:

   // src/Action/MyAction.php
   namespace AppBundle\Action;
   class MyAction {
       public function execute($id) {
           return ['id' => $id];
       }
   }
   

   Define in services.yml:

   AppBundle\Action\MyAction:
       arguments: ['@some.service']
       tags: ['app.action']
   

2. Tagged Services: Use GenericCompilerPass to inject tagged services (e.g., listeners, handlers):

   # services.yml
   AppBundle\Service\EventDispatcher:
       tags: ['app.event_dispatcher']
   

   Configure in config/packages/app.yaml:

   sidus_base:
       compiler_passes:
           - { tag: 'app.event_dispatcher', target: 'AppBundle\Service\EventDispatcher' }
   

3. Param Converters: Extend AbstractParamConverter for custom types:

   namespace AppBundle\ParamConverter;
   use Sidus\BaseBundle\ParamConverter\AbstractParamConverter;
   
   class CustomConverter extends AbstractParamConverter {
       public function supports(Parameter $parameter) { /* ... */ }
       public function convert($value, Parameter $parameter) { /* ... */ }
   }
   

   Register in services.yml:

   AppBundle\ParamConverter\CustomConverter:
       tags: ['param_converter']
   

Integration Tips

• Symfony Flex: Manually register the bundle if using Symfony Flex (no autoconfiguration).
• Doctrine Integration: Use DateTimeUtility::parse for form type data transformers:

  $date = DateTimeUtility::parse($rawInput, ['Y-m-d', 'd/m/Y']);
  

• Translation Fallbacks: Chain translators with TranslatorUtility:

  $translator = new TranslatorUtility($translator);
  $message = $translator->trans([
      'key1', 'key2', 'default'
  ], [], 'bundle');
  

• Validation: Load constraints dynamically:

  $constraints = BaseLoader::loadConstraints([
      'NotBlank',
      'Length' => ['min' => 3]
  ]);
  $validator->validate($data, $constraints);
  

Gotchas and Tips

Pitfalls

1. Service Naming:

   • Route names must match service IDs exactly (case-sensitive). Example:

     # Correct
     AppBundle\Action\MyAction: ~  # Route: AppBundle_MyAction
     # Incorrect (will fail silently)
     app.my_action: ~  # Route: AppBundle_MyAction
     

   • Debug: Use bin/console debug:container to verify service IDs.

2. Compiler Pass Timing:

   • GenericCompilerPass runs after services are loaded. Misconfigured passes may throw:

     Service "foo.bar" has a dependency on another service "baz.qux" that does not exist.
     

   • Fix: Ensure tagged services are defined before the pass runs (use priority in services.yml).

3. Routing Overrides:

   • Overriding routes in config/routes.yaml may break service-based routing. Prefer:

     # config/routes.yaml
     AppBundle_MyAction:
         path: /custom-path/{id}
     

4. Deprecated Symfony 3:

   • Some features (e.g., AbstractParamConverter) may not work as expected in Symfony 4+. Test thoroughly.

Debugging Tips

1. Service Dumping:

   bin/console debug:container AppBundle\Action\MyAction
   

   Check for missing arguments or circular references.

2. Compiler Pass Debugging:

   • Enable verbose mode:

     bin/console debug:container --env=dev --dump=xml
     

   • Inspect compiled services in var/cache/dev/.

3. Routing Debugging:

   • List all routes:

     bin/console debug:router
     

   • Verify _service and _method are set correctly.

Extension Points

1. Custom Compiler Passes: Extend GenericCompilerPass for complex dependency injection:

   namespace AppBundle\DependencyInjection\Compiler;
   use Sidus\BaseBundle\DependencyInjection\Compiler\GenericCompilerPass;
   
   class MyCustomPass extends GenericCompilerPass {
       protected function getTag() { return 'app.my_tag'; }
       protected function addServiceCall($service, $taggedServices) { /* ... */ }
   }
   

   Register in FooBarExtension:

   public function load(array $configs, ContainerBuilder $container) {
       $container->addCompilerPass(new MyCustomPass());
   }
   

2. Param Converter Extensions: Override supports() and convert() for custom types (e.g., UUIDs, nested objects).

3. Validator Extensions: Extend BaseLoader to support custom constraint formats:

   BaseLoader::addLoader('custom', function($config) {
       return new CustomConstraint($config);
   });
   

Configuration Quirks

• DateTime Parsing: DateTimeUtility::parse defaults to DateTime::createFromFormat(). For timezone-aware parsing:

  $date = DateTimeUtility::parse($input, ['Y-m-d'], new \DateTimeZone('UTC'));
  

• Translation Domains: TranslatorUtility uses the default domain unless specified:

  $translator->trans(['key'], [], 'custom_domain');
  

• Validator Groups: BaseLoader ignores groups in constraints. Manually add:

  $constraints = BaseLoader::loadConstraints([...]);
  $constraints->groups = ['Default', 'CustomGroup'];