Zgw Stuff Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run in your Symfony project root:

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

   For Dockerized environments:

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

2. Install Schemas as Entities Execute the console command to generate entities from schemas:

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

   Or in Docker:

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

3. Verify Installation Check if the bundle is registered in config/bundles.php and clear the cache:

   php bin/console cache:clear
   

First Use Case: Extending ZGW Functionality

Use this bundle as a template to create a custom bundle for ZGW (Zaken Gateway) integration. Start by:

• Forking the template repository.
• Replacing placeholder logic with your custom API endpoints, entities, and services.
• Leveraging the commongateway:install command to auto-generate entities from your schemas.

Implementation Patterns

Core Workflows

1. Bundle Creation Workflow

   • Use the template to scaffold a new bundle with pre-configured:
     • Symfony Flex recipe.
     • Doctrine entities (via ZGWStuffBundle\Installer\Installer).
     • Console commands for schema installation.
   • Example structure:

     src/
     ├── Controller/
     ├── Entity/
     ├── Installer/
     │   └── Installer.php       # Extend to add custom schema logic
     ├── Resources/
     │   ├── config/
     │   └── migrations/
     └── ZGWStuffBundle.php
     

2. Schema-to-Entity Conversion

   • Override the Installer class to define custom schema mappings:

     // src/Installer/CustomInstaller.php
     namespace App\Installer;
     
     use CommonGateway\ZGWStuffBundle\Installer\Installer;
     
     class CustomInstaller extends Installer
     {
         protected function getSchemaFiles(): array
         {
             return [
                 __DIR__.'/../Resources/config/schemas/custom_schema.json',
             ];
         }
     }
     

   • Register the installer in services.yaml:

     services:
         App\Installer\CustomInstaller:
             tags: [zgw.installer]
     

3. API Integration

   • Extend the base ZGWStuffBundle controller to handle custom API routes:

     // src/Controller/CustomController.php
     namespace App\Controller;
     
     use CommonGateway\ZGWStuffBundle\Controller\ZGWStuffController;
     
     class CustomController extends ZGWStuffController
     {
         public function customAction()
         {
             // Your custom logic
         }
     }
     

   • Route the controller in config/routes.yaml:

     app_custom:
         resource: "@App\Controller\CustomController"
         type: annotation
     

4. Event-Driven Extensions

   • Listen to ZGW events (e.g., zgw.schema.installed) to trigger post-install logic:

     // src/EventListener/CustomListener.php
     namespace App\EventListener;
     
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use CommonGateway\ZGWStuffBundle\Event\SchemaInstalledEvent;
     
     class CustomListener implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 SchemaInstalledEvent::NAME => 'onSchemaInstalled',
             ];
         }
     
         public function onSchemaInstalled(SchemaInstalledEvent $event)
         {
             // Post-install logic (e.g., seed data, run migrations)
         }
     }
     

Integration Tips

• Doctrine Migrations: Use the make:migration command after schema installation to version-control database changes.
• Testing: Mock the Installer and ZGWStuffController in PHPUnit tests to isolate bundle logic.
• Configuration: Override bundle parameters in config/packages/zgw_stuff.yaml:

  zgw_stuff:
      default_locale: nl_NL
      api_base_url: https://api.example.com
  

Gotchas and Tips

Pitfalls

1. Schema Installation Order

   • Running commongateway:install multiple times may cause duplicate entity generation. Use --force cautiously:

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

   • Fix: Check for existing entities before installation in a custom Installer.

2. Entity Naming Conflicts

   • The auto-generated entities use snake_case by default. Override the Installer to customize naming:

     protected function getEntityNamespace(): string
     {
         return 'App\Entity\Custom';
     }
     

3. Missing Dependencies

   • The bundle assumes Symfony 5.4+ and Doctrine ORM. If using Symfony 6+, update the composer.json dependencies manually:

     "require": {
         "symfony/framework-bundle": "^6.0",
         "doctrine/orm": "^2.10"
     }
     

4. Console Command Scope

   • The commongateway:install command is bundle-specific. To avoid conflicts, prefix custom commands:

     php bin/console app:install:schemas
     

Debugging

• Schema Validation Errors

  • Validate JSON schemas before installation using a tool like JSON Schema Validator.
  • Check the Installer logs for parsing errors:

    php bin/console debug:config zgw_stuff | grep -i schema
    

• Entity Generation Issues

  • Clear the cache and regenerate metadata:

    php bin/console doctrine:cache:clear-metadata
    php bin/console make:entity --regenerate App
    

Extension Points

1. Custom Installer Logic Extend the Installer class to add pre/post-install hooks:

   protected function preInstall(): void
   {
       $this->createBackupDatabase();
   }
   
   protected function postInstall(): void
   {
       $this->runMigrations();
   }
   

2. Dynamic Schema Loading Load schemas from external sources (e.g., API) by overriding getSchemaFiles():

   protected function getSchemaFiles(): array
   {
       $schemas = $this->fetchRemoteSchemas();
       return array_map(fn($schema) => tempnam(sys_get_temp_dir(), 'zgw_'), $schemas);
   }
   

3. API Client Customization Extend the base HTTP client in ZGWStuffController:

   protected function createClient(): ClientInterface
   {
       $client = parent::createClient();
       $client->setDefaultOption('auth', 'Bearer ' . $this->getApiToken());
       return $client;
   }
   

4. Event Dispatching Trigger custom events during installation:

   $event = new CustomEvent($this->getSchema());
   $this->dispatcher->dispatch($event, CustomEvent::NAME);
   

Configuration Quirks

• Bundle Prefix: The bundle uses zgw_stuff as the default config key. Override in config/packages/zgw_stuff.yaml if needed:

  zgw_stuff:
      prefix: custom_zgw
  

• Environment Variables: Use %env(ZGW_API_KEY)% in config/services.yaml for sensitive data:

  parameters:
      zgw.api_key: '%env(ZGW_API_KEY)%'