Zgw Zds Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require common-gateway/zgw-zds-bundle:dev-main
   

   For Dockerized environments:

   docker-compose exec php composer require common-gateway/zgw-zds-bundle:dev-main
   

2. Install Schemas as Entities:

   php bin/console commongateway:install common-gateway/zgw-zds-bundle
   

   Or in Docker:

   docker-compose exec php bin/console commongateway:install common-gateway/zgw-zds-bundle
   

3. Verify Installation: Check if the bundle is registered in config/bundles.php and if the ZGWZdsBundle namespace is autoloaded.

First Use Case

Use this bundle as a template to scaffold a new Symfony Flex bundle for CommonGateway projects. It provides a minimal structure for:

• Doctrine entities (via commongateway:install command).
• Basic bundle configuration.
• Integration with CommonGateway’s admin UI (documentation pending).

Implementation Patterns

Workflow for Creating a New Bundle

1. Template Usage:

   • Fork or use the GitHub template.
   • Replace ZGWZdsBundle with your bundle’s namespace (e.g., MyCompanyMyBundle).

2. Directory Structure:

   src/
   ├── DependencyInjection/          # Configuration (Extension.php, MyCompanyMyExtension.php)
   ├── Entity/                      # Doctrine entities (e.g., MyEntity.php)
   ├── Resources/config/            # Doctrine ORM/YAML/XML mappings
   ├── Resources/public/            # Static assets
   └── MyCompanyMyBundle.php        # Bundle class
   

3. Configuration:

   • Extend CommonGatewayBundle in your MyCompanyMyBundle.php:

     class MyCompanyMyBundle extends Bundle implements CommonGatewayBundleInterface
     {
         public function getPath(): string
         {
             return \dirname(__DIR__);
         }
     }
     

   • Define services in DependencyInjection/MyCompanyMyExtension.php:

     public function load(array $configs, ContainerBuilder $container)
     {
         $container->loadFromExtension('doctrine', [
             'orm' => [
                 'mappings' => [
                     'MyCompany' => __DIR__.'/../../Entity',
                 ],
             ],
         ]);
     }
     

4. Command Integration:

   • Override the commongateway:install command to include your entities:

     php bin/console make:command MyInstallCommand
     

     Then register it in DependencyInjection/MyCompanyMyExtension.php:

     $container->setDefinition('my.installer', new Definition(MyInstaller::class));
     

5. Admin UI Integration (TBD):

   • Once the admin UI docs are available, register your entities as resources:

     # config/packages/common_gateway.yaml
     commongateway:
         resources:
             - MyCompany\MyBundle\Entity\MyEntity
     

Integration Tips

• Doctrine Migrations: Generate migrations for your entities:

  php bin/console make:migration
  php bin/console doctrine:migrations:migrate
  

• Testing: Use PHPUnit with Symfony’s test utilities:

  php bin/console make:test
  

• Docker: Ensure your Dockerfile includes:

  RUN composer require common-gateway/zgw-zds-bundle:dev-main
  

Gotchas and Tips

Pitfalls

1. Missing Admin UI Docs:

   • The README mentions @todo! for admin UI installation. Check the CommonGateway documentation for updates or ask in their Slack/Discord.

2. Dev Dependency:

   • The package is installed via :dev-main, which may introduce instability. Pin to a stable release if available:

     composer require common-gateway/zgw-zds-bundle:^1.0
     

3. Entity Overrides:

   • If you reuse entity names (e.g., ZdsEntity), conflicts may arise. Prefix with your bundle name (e.g., MyBundleZdsEntity).

4. Command Namespace Collisions:

   • Ensure your custom commands (e.g., MyInstallCommand) don’t clash with existing ones. Use unique namespaces:

     namespace MyCompany\MyBundle\Command;
     

Debugging

• Check Bundle Registration: Run php bin/console debug:container MyCompanyMyBundle to verify the bundle is loaded.
• Doctrine Errors: If entities fail to install, check:

  php bin/console doctrine:schema:validate
  

• Composer Autoload: After adding new classes, run:

  composer dump-autoload
  

Configuration Quirks

1. Flex Recipe: The bundle uses Symfony Flex recipes. If you encounter issues, ensure your composer.json has:

   "extra": {
       "symfony": {
           "allow-contrib": true
       }
   }
   

2. Environment Variables: The commongateway:install command may require environment variables (e.g., DATABASE_URL). Set them in .env:

   DATABASE_URL="mysql://user:pass@127.0.0.1:3306/db_name"
   

Extension Points

1. Custom Installer: Extend the commongateway:install command by creating a custom installer class:

   use CommonGateway\Installer\InstallerInterface;
   
   class MyCustomInstaller implements InstallerInterface
   {
       public function install(): void
       {
           // Add your logic (e.g., load fixtures)
       }
   }
   

   Register it in your extension:

   $container->setAlias('my.installer', MyCustomInstaller::class);
   

2. Event Subscribers: Listen to CommonGateway events (e.g., CommonGatewayEvents::POST_INSTALL) to run post-install logic:

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class MySubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'common_gateway.post_install' => 'onPostInstall',
           ];
       }
   
       public function onPostInstall()
       {
           // Your logic
       }
   }
   

3. API Integration: If your bundle interacts with APIs, use Symfony’s HTTP client:

   use Symfony\Contracts\HttpClient\HttpClientInterface;
   
   class MyApiService
   {
       public function __construct(private HttpClientInterface $client) {}
   
       public function fetchData(): array
       {
           return $this->client->request('GET', 'https://api.example.com/data')->toArray();
       }
   }
   

   Register the service in your extension:

   $container->setService('my.api_service', MyApiService::class);