Getting Started

Minimal Steps

Installation

composer require common-gateway/zgw-bundle

Add to config/bundles.php:

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

Configuration Publish the default config:

php bin/console config:dump-reference CommonGateway\ZGWBundle\Resources/config/zgw.yaml

Configure in config/packages/zgw.yaml:

zgw:
    api_version: '1.5.1'
    base_uri: '%env(ZGW_BASE_URI)%'
    client_id: '%env(ZGW_CLIENT_ID)%'
    client_secret: '%env(ZGW_CLIENT_SECRET)%'

First Use Case Fetch a case (zaak) via the API:

use CommonGateway\ZGWBundle\Client\ZGWClient;

$client = $this->container->get(ZGWClient::class);
$case = $client->getZaak('urn:uuid:123e4567-e89b-12d3-a456-426614174000');

Where to Look First

Documentation: Check INSTALLATION.md and the GitHub Wiki (if available).
Symfony Console Commands: Run php bin/console list zgw to see available commands.
Entity Extensions: Explore src/Entity/ for default models (e.g., Zaak, ZaakType, Document).

Implementation Patterns

Core Workflows

API Client Integration Use the ZGWClient to interact with ZGW APIs:

// Fetch a case with minimal data (filtering)
$case = $client->getZaak('urn:uuid:...', ['fields' => ['zaaknummer', 'omschrijving']]);

// Create a case
$newCase = $client->createZaak([
    'zaaktype' => 'urn:uuid:zaaktype-uuid',
    'omschrijving' => 'New case description',
]);

Event-Driven Extensions Extend default entities via the extend pattern:

// In a service or bundle
$zaak = $client->getZaak('urn:uuid:...');
$zaak->extend('custom_field', 'value'); // Add custom data
$zaak->save(); // Persist extended data (if using Doctrine)

Filtering and Minimalization Leverage filtering to reduce payload size:

// Fetch only required fields for a case type
$caseType = $client->getZaakType('urn:uuid:zaaktype-uuid', [
    'fields' => ['omschrijving', 'vertrouwelijkheidaanduiding'],
]);

Authentication Handle OAuth2 via the bundle’s built-in client:

# config/packages/zgw.yaml
zgw:
    auth:
        token_url: '%env(ZGW_TOKEN_URL)%'
        scopes: ['read', 'write']

Integration Tips

Symfony Messenger: Use the bundle’s message handlers to process ZGW events asynchronously.

Doctrine ORM: Map ZGW entities to Doctrine entities for local persistence:

# config/packages/doctrine.yaml
orm:
    mappings:
        ZGW:
            type: attribute
            dir: '%kernel.project_dir%/vendor/common-gateway/zgw-bundle/src/Entity'
            prefix: 'CommonGateway\ZGWBundle\Entity'
            alias: ZGW

API Versioning: Always specify the api_version in config to avoid breaking changes.

Gotchas and Tips

Pitfalls

API Version Lock-In
- The bundle defaults to 1.5.1. Ensure your code doesn’t assume newer ZGW features unless explicitly configured.
- Fix: Pin the version in zgw.yaml and test upgrades carefully.
Caching Headaches
- The client may cache responses aggressively. Clear caches when testing:
```
php bin/console cache:clear
```
- Tip: Disable caching in dev environment:
```
zgw:
    client:
        cache_enabled: '%kernel.debug%'
```
Extended Data Persistence
- Custom extended data ($zaak->extend()) is not automatically persisted unless configured.
- Solution: Use a custom Doctrine listener or repository to handle extended fields.

Rate Limiting

ZGW APIs enforce rate limits. Handle 429 Too Many Requests gracefully:

try {
    $client->getZaak('urn:uuid:...');
} catch (\CommonGateway\ZGWBundle\Exception\RateLimitExceededException $e) {
    sleep($e->getRetryAfter());
    retry();
}

UUID Handling

ZGW uses URNs (e.g., urn:uuid:...). Validate UUIDs before passing them to the client:

if (!\Ramsey\Uuid\Uuid::isValid($urn)) {
    throw new \InvalidArgumentException('Invalid URN format');
}

Debugging

Enable Verbose Logging
```
zgw:
    client:
        debug: true
```
Logs will appear in var/log/dev.log.
Inspect Raw Responses Use the ZGWClient with debug: true to dump raw API responses:
```
$client->setDebug(true);
$response = $client->getZaak('urn:uuid:...');
```

Extension Points

Custom Entity Mappers Override default entity mappings by creating a custom mapper:

// src/Service/CustomZaakMapper.php
use CommonGateway\ZGWBundle\Mapper\ZaakMapper;

class CustomZaakMapper extends ZaakMapper {
    public function map(array $data): Zaak {
        $zaak = parent::map($data);
        $zaak->setCustomField($data['custom_field'] ?? null);
        return $zaak;
    }
}

services:
    CommonGateway\ZGWBundle\Mapper\ZaakMapper:
        alias: App\Service\CustomZaakMapper

Event Subscribers Listen to ZGW events (e.g., zgw.zaak.created):

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use CommonGateway\ZGWBundle\Event\ZaakEvent;

class ZaakSubscriber implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            ZaakEvent::CREATED => 'onZaakCreated',
        ];
    }

    public function onZaakCreated(ZaakEvent $event) {
        // Handle new case
    }
}

Custom API Endpoints Extend the client to support non-standard ZGW endpoints:

// src/Client/CustomZGWClient.php
use CommonGateway\ZGWBundle\Client\ZGWClient;

class CustomZGWClient extends ZGWClient {
    public function getCustomEndpoint(string $path, array $data = []) {
        return $this->request('GET', "/custom/{$path}", $data);
    }
}

Configuration Quirks

Base URI Trailing Slash Ensure base_uri in zgw.yaml does not end with a slash:
```
zgw:
    base_uri: 'https://api.example.com'  # No trailing slash!
```
Environment Variables Use env() in config for sensitive data:
```
zgw:
    client_id: '%env(ZGW_CLIENT_ID)%'
    client_secret: '%env(ZGW_CLIENT_SECRET)%'
```
Never hardcode secrets in zgw.yaml.
Default Fields The bundle includes default fields for entities. To exclude them, use:
```
$client->getZaak('urn:uuid:...', ['fields' => []]); // Empty array = no fields
```

Zgw Bundle Laravel Package