Getting Started

Minimal Steps to First Use

Clone or Fork the Template Start by cloning or forking the ZGWToZDSBundle repository to create your own bundle. This serves as a boilerplate for extending Common Gateway functionality.
Install Dependencies Navigate to your project root and run:
```
composer install
```
Ensure your environment (PHP, Composer, or Docker) meets the requirements.

Register the Bundle Add your bundle to config/bundles.php in your Symfony application:

return [
    // ...
    CommonGateway\ZGWToZDSBundle\CommonGatewayZGWToZDSBundle::class => ['all' => true],
];

Install via Admin UI or CLI
- Admin UI: Navigate to the Plugins tab in the Common Gateway admin interface to discover, select, and install your bundle.
- CLI: Run the installation command:
```
php bin/console commongateway:install common-gateway/your-bundle-name
```
Verify Installation Check the Symfony logs or the admin UI to confirm your bundle is active and discoverable.

First Use Case: Extending Gateway Functionality

Use this bundle to create a custom plugin that:

Adds new API endpoints for ZGW-to-ZDS communication.
Integrates with existing Common Gateway workflows (e.g., schema validation, request/response handling).
Example: Extend the ZGWToZDSBundle to handle a specific ZDS (Zaken Dossier System) use case, such as fetching or updating case data.

Implementation Patterns

Core Workflows

Bundle Structure Follow the template’s structure:

src/
├── DependencyInjection/          # Configuration and services
│   ├── CommonGatewayZGWToZDSExtension.php
│   └── CommonGatewayZGWToZDSCompilerPass.php
├── Resources/config/             # YAML/XML config for services, routes, etc.
├── Resources/public/              # Static assets (JS/CSS)
└── CommonGatewayZGWToZDSBundle.php # Bundle class

Service Integration Define services in DependencyInjection/CommonGatewayZGWToZDSExtension.php:

public function load(array $configs, ContainerBuilder $container)
{
    $container->loadFromExtension('framework', [
        'router' => [
            'resource' => '%kernel.project_dir%/config/routes.yaml',
            'type' => 'yaml',
        ],
    ]);
}

Route Configuration Add routes in Resources/config/routes.yaml:

common_gateway_zgw_to_zds:
    resource: "@CommonGatewayZGWToZDSBundle/Resources/config/routes.yaml"
    type: "yaml"

Event Listeners/Subscribers Use Symfony events (e.g., kernel.request, zgw.message) to hook into Common Gateway’s lifecycle:

// src/EventListener/ZGWToZDSListener.php
public function onZGWMessage(ZGWMessageEvent $event)
{
    $message = $event->getMessage();
    // Custom logic for ZDS integration
}

Schema Management Use the commongateway:install command to register schemas (e.g., OpenAPI/Swagger definitions) for your endpoints.

Integration Tips

Leverage Common Gateway’s Core Services Inject services like CommonGateway\Core\ZGW\ZGWClient or CommonGateway\Core\ZDS\ZDSApi to interact with ZGW/ZDS systems:
```
public function __construct(private ZGWClient $zgwClient, private ZDSApi $zdsApi) {}
```
Use Compiler Passes Modify container configuration dynamically via CommonGatewayZGWToZDSCompilerPass (e.g., for environment-specific settings).
Admin UI Plugin Discovery Ensure your bundle implements the CommonGateway\Plugin\PluginInterface to be auto-discovered in the admin UI.
Testing Use Symfony’s Test\WebTestCase or PHPUnit to test routes, services, and event listeners. Mock dependencies like ZGWClient or ZDSApi for isolation.

Gotchas and Tips

Pitfalls

Bundle Auto-Discovery
- Issue: Bundles may not appear in the admin UI if config/bundles.php is misconfigured or the bundle lacks the PluginInterface.
- Fix: Verify the bundle is enabled in bundles.php and implements PluginInterface. Clear cache after changes:
```
php bin/console cache:clear
```
Schema Installation Failures
- Issue: The commongateway:install command may fail if schemas are malformed or dependencies are missing.
- Fix: Validate schemas against the Common Gateway schema standards (e.g., OpenAPI 3.0). Check logs for specific errors:
```
php bin/console debug:container | grep schema
```
Event Subscriber Conflicts
- Issue: Multiple subscribers for the same event (e.g., zgw.message) may cause unexpected behavior.
- Fix: Use priority in subscriber tags or namespace event names (e.g., zgw.message.your_bundle).
Dependency Version Mismatches
- Issue: Conflicts between common-gateway/core and your bundle’s dependencies.
- Fix: Align versions in composer.json or use replace to enforce compatibility:
```
"replace": {
    "common-gateway/core": "1.0.*"
}
```

Debugging Tips

Enable Debug Mode Set APP_ENV=dev in .env and enable Symfony’s debug toolbar for detailed logs and requests.

Log Custom Events Use Symfony’s logger in event subscribers:

use Psr\Log\LoggerInterface;

public function __construct(private LoggerInterface $logger) {}

public function onZGWMessage(ZGWMessageEvent $event)
{
    $this->logger->info('ZGW message received', ['message' => $event->getMessage()]);
}

Check Plugin Installation Logs Run the install command with -v for verbose output:
```
php bin/console commongateway:install common-gateway/your-bundle -v
```

Extension Points

Custom Commands Extend the bundle with custom Symfony commands (e.g., zgw:zds:sync) by creating a Command class in src/Command/ and register it in DependencyInjection/.
Dynamic Configuration Use Extension methods to load environment-specific configurations (e.g., API keys, endpoints) from .env or YAML files.

API Client Extensions Extend ZGWClient or ZDSApi by creating a decorator or proxy service:

// src/Service/ZGWClientDecorator.php
public function sendRequest(Request $request)
{
    // Pre/post-process requests before delegating to the wrapped client
    return $this->zgwClient->sendRequest($request);
}

Webhook Handlers Add support for ZDS webhooks by implementing a WebhookHandlerInterface and registering it as a service.
Localization Use Symfony’s translation system (translator) to support multiple languages in your plugin’s UI or responses.

Zgw To Zds Bundle Laravel Package