App Registry Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require aeruz/app-registry-bundle
   

   Enable it in config/bundles.php:

   Aeruz\AppRegistryBundle\AppRegistryBundle::class => ['all' => true],
   

2. First Use Case: Registering an Application Define an application in config/packages/app_registry.yaml:

   aeruz_app_registry:
       applications:
           my_app:
               name: "My Application"
               enabled: true
               routes: ["app_*"]
               middleware: ["auth", "locale"]
   

3. Accessing the Registry Inject the AppRegistry service in a controller or service:

   use Aeruz\AppRegistryBundle\Registry\AppRegistry;
   
   public function __construct(private AppRegistry $registry) {}
   
   public function checkApp(): void
   {
       $app = $this->registry->get('my_app');
       if ($app) {
           // Application is registered and enabled
       }
   }
   

4. Routing Integration Use the app_registry extra in your routes (config/routes.yaml):

   app_home:
       path: /
       controller: App\Controller\HomeController::index
       app_registry: my_app
   

Implementation Patterns

Core Workflows

1. Dynamic Application Switching Use the AppRegistry to conditionally load services, routes, or middleware based on the active application:

   $activeApp = $this->registry->getActiveApp();
   if ($activeApp->hasMiddleware('auth')) {
       $this->addMiddleware($activeApp->getMiddleware('auth'));
   }
   

2. Service Provider Isolation Extend the bundle’s AppRegistryServiceProvider to bind application-specific services:

   use Aeruz\AppRegistryBundle\DependencyInjection\AppRegistryExtension;
   
   public function load(array $configs, ContainerBuilder $container)
   {
       $loader = new Loader\YamlFileLoader($container, new FileLocator(__DIR__.'/../Resources/config'));
       $loader->load('services/my_app.yaml');
   }
   

3. Event-Driven Extensions Listen to AppRegistryEvents (e.g., AppRegisteredEvent) to react to application lifecycle changes:

   $dispatcher->addListener(AppRegistryEvents::APP_REGISTERED, function (AppRegisteredEvent $event) {
       $this->logger->info(sprintf('Registered app: %s', $event->getApp()->getName()));
   });
   

Integration Tips

• Symfony Flex Recipes: Create a custom recipe to scaffold application-specific configurations.
• Twig Integration: Pass the active application to templates via a global variable:

  {% if app_registry.activeApp %}
      <div class="app-header">{{ app_registry.activeApp.name }}</div>
  {% endif %}
  

• API Platform: Use the registry to dynamically configure API resources:

  # config/api_platform/resources.yaml
  resources:
      App\Entity\Post:
          app_registry: my_app
          operations:
              - GET
              - POST
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies Avoid circular references between applications (e.g., app_a requiring app_b, which in turn requires app_a). Use lazy-loading or interfaces to decouple dependencies.

2. Middleware Ordering Middleware defined in the registry runs after global middleware. Override the kernel.middleware config if ordering is critical:

   # config/packages/framework.yaml
   framework:
       middleware: ['app_registry_middleware', 'other_middleware']
   

3. Route Precedence Routes with app_registry take precedence over global routes only if the application is active. Test with:

   php bin/console debug:router | grep "app_registry"
   

Debugging

• Dump the Registry Use the debug command to inspect registered applications:

  php bin/console debug:app-registry
  

• Event Listener Logging Enable Symfony’s event dispatcher debug mode:

  # config/packages/dev/framework.yaml
  framework:
      router:
          debug: "%kernel.debug%"
      profiler: { only_exceptions: false }
  

Extension Points

1. Custom Application Classes Extend Aeruz\AppRegistryBundle\Model\App to add metadata:

   namespace App\Model;
   
   use Aeruz\AppRegistryBundle\Model\App as BaseApp;
   
   class App extends BaseApp
   {
       public function getIcon(): string
       {
           return $this->getOption('icon', 'default_icon');
       }
   }
   

   Register the custom class in config/packages/app_registry.yaml:

   aeruz_app_registry:
       app_class: App\Model\App
   

2. Dynamic Application Loading Implement Aeruz\AppRegistryBundle\Loader\AppLoaderInterface to load applications from a database or external API:

   class DatabaseAppLoader implements AppLoaderInterface
   {
       public function load(): array
       {
           return $this->db->fetchAll('SELECT * FROM applications');
       }
   }
   

   Bind it in services.yaml:

   services:
       Aeruz\AppRegistryBundle\Loader\AppLoaderInterface: '@App\Loader\DatabaseAppLoader'
   

3. Conditional Application Activation Override AppRegistry::getActiveApp() to implement custom logic (e.g., subdomain-based activation):

   public function getActiveApp(): ?App
   {
       $subdomain = $this->requestStack->getMainRequest()->getHost();
       return $this->apps->get($subdomain);
   }