Outer Extension Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require blast-project/outer-extension-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Blast\OuterExtensionBundle\OuterExtensionBundle::class => ['all' => true],
   ];
   

2. First Use Case Enable outer extensions for a Doctrine entity by annotating it with @OuterExtension:

   use Blast\OuterExtensionBundle\Annotation\OuterExtension;
   
   /**
    * @OuterExtension
    */
   #[ORM\Entity]
   class User
   {
       // ...
   }
   

   Verify the extension is registered via:

   php bin/console debug:container blast.outer_extension.manager
   

Implementation Patterns

Core Workflow

1. Entity Integration

   • Use the @OuterExtension annotation or YAML/XML configuration to mark entities.
   • Example YAML (config/outer_extensions.yaml):

     resources:
         Blast\YourBundle\Entity\User:
             extensions:
                 - Blast\OuterExtensionBundle\Extension\ExampleExtension
     

2. Extension Development Extend the base OuterExtensionInterface:

   namespace Blast\OuterExtensionBundle\Extension;
   
   use Blast\OuterExtensionBundle\Extension\OuterExtensionInterface;
   
   class ExampleExtension implements OuterExtensionInterface
   {
       public function load(OuterExtensionManager $manager, $entityName): void
       {
           // Custom logic (e.g., add virtual fields, modify queries)
       }
   }
   

3. Query Modification Hook into Doctrine events via the manager:

   $manager = $container->get('blast.outer_extension.manager');
   $manager->addListener('user', function (User $user, Event $event) {
       // Pre/post-load logic
   });
   

4. Symfony Service Integration Inject the manager into services:

   use Blast\OuterExtensionBundle\Manager\OuterExtensionManager;
   
   class UserService
   {
       public function __construct(private OuterExtensionManager $extensionManager) {}
   }
   

Gotchas and Tips

Pitfalls

1. Annotation vs. Config

   • Prefer YAML/XML over annotations for complex setups (annotations are parsed at runtime).
   • Debug missing extensions with:

     php bin/console debug:container --parameters | grep outer_extension
     

2. Caching Issues

   • Clear cache after adding new extensions:

     php bin/console cache:clear
     

   • Extensions may not reflect changes if the entity metadata cache is stale.

3. Doctrine Event Conflicts

   • Avoid duplicate listeners for the same event (e.g., prePersist). Use unique tags:

     $manager->addListener('user', $listener, 'user.pre_persist', 10);
     

Debugging Tips

• Log Extension Loading Enable debug mode and check logs for OuterExtensionBundle entries.
• Inspect Entities Use the debug command to list active extensions:

  php bin/console debug:outer-extension
  

• Test Isolation Test extensions in isolation with a fresh Doctrine entity manager:

  $em = EntityManager::create([], new \Doctrine\DBAL\Configuration());
  $manager->setEntityManager($em);
  

Extension Points

1. Custom Metadata Drivers Override the default driver to support custom storage (e.g., database-backed extensions):

   $manager->setMetadataDriver(new CustomDriver());
   

2. Event Priorities Adjust listener priorities to control execution order (higher numbers = later execution).
3. Lazy Loading Use OuterExtensionManager::loadExtensionsLazy() to defer extension loading until first use.