Skip to content

Getting started

Jump to bottom
Sander edited this page Jan 14, 2025 · 3 revisions

Documentation

This PHP packages offers an implementation of the 'Zaakgericht Werken' (ZGW) API's, in accordance with the Gemma standards. The library enables developers to easily integrate and access the ZGW API's of various registries.

Registry support

Client 📥 ZRC 🗂️ ZTC 📄 DRC 🔐 Auth
OpenZaak ✅ 1.5.1 ✅ 1.5.1 ✅ 1.5.1 JWT tokens
RxMission ✅ 1.5.1 ✅ 1.5.1 ✅ 1.5.1 JWT tokens
XXLLNC ✅ unkown version ✅ unkown version ✅ 1.5.1 Pre-distributed API key
DecosJoin unknown unknown unknown unknown
Procura unknown unknown unknown unknown

Before you start

At a high level, this package can be broken down in three elements:

  1. Clients: they represent the connection to a registry. For example: OpenZaak.
  2. Endpoints: an endpoint within a component. For example: Zaken in the ZRC component or Enkelvoudiginformatieobjecten in the DRC component.
  3. Entities: typed objects of data, usually returned from the API. For example a 'Zaak' or Objectinformatie.

Good to know: names of most endpoints and entities are not translated. Some classes therefore have names that is a mix of Dutch and English.

In most cases you'd:

  1. Resolve your client of your choice (e.g. OpenZaak)
  2. Access the endpoint you need through the client (e.g. Zaken)
  3. Request the entity of your choice through the endpoint (e.g. Zaak)

Clients

This package supports multiple ZGW 'clients'. A client represents the connection to a registry. For example: OpenZaak. It does not come with a pre-configured client. This will show you how to add and access one.

Adding a client

Zaaksysteem clients are easily configured and resolved through the OWC\ZGW\ApiClientManager class. Every client requires two elements: a collection of URLs and some credentials. For both are designated classes available:

  1. OWC\ZGW\ApiUrlCollection: contains URLs to the endpoints
  2. OWC\ZGW\ApiCredentials: contains credentials and (optionally!) SSL certificates

Important

Decos JOIN has a custom implementation of the ApiCredentials class. Use the OWC\ZGW\Clients\DecosJoin\ApiCredentials class to correctly set the client secret for the ZRC component.

Add any Zaaksysteem client through the addClient() method on the ApiClientManager. It requires:

  • a unique name, e.g. 'my-oz-client',
  • a fully qualified class name of the client implementation,
  • the ApiUrlCollection instance,
  • and the ApiCredentials instance.
use OWC\ZGW\ApiCredentials;
use OWC\ZGW\ApiClientManager;
use OWC\ZGW\ApiUrlCollection;

$manager = new ApiClientManager();

$uris = new ApiUrlCollection();
$uris->setApiVersion('1.5.0');
$uris->setZakenEndpoint('https://url.com/zaken/api/v1');
$uris->setCatalogiEndpoint('https://url.com/catalogi/api/v1');
$uris->setDocumentenEndpoint('https://url.com/documenten/api/v1');

$credentials = new ApiCredentials();
$credentials->setClientId('client_id');
$credentials->setClientSecret('client_secret');

$manager->addClient('my-oz-client', OWC\ZGW\Clients\OpenZaak\Client::class, $credentials, $uris);

Accessing a client

After adding a client, you'll be able to access a fully built client through the getClient(string $name) method!

// Resolve it by it's name
$client = $manager->getClient('my-oz-client');

Using helper functions

The ApiClientManager class has some helper functions which can be accessed after initializing the class. These helper functions are within the OWC\ZGW namespace.

  1. apiClient(string $name): returns any defined client
  2. apiClientManager(): returns the ApiClientManager class
  3. resolve(string $name): quickly access any definition in the container
  4. container(): returns the internal DI\Container instance

Build a client

The easiest way to build any configured zaaksysteem client:

use function OWC\ZGW\apiClient;

apiClient(string $name): OWC\ZGW\Contracts\AbstractClient

All clients inherit from OWC\ZGW\Contracts\AbstractClient.

ApiClientManager access

use function OWC\ZGW\apiClientManager;

apiClientManager(): OWC\ZGW\ApiClientManger

Container access

Use the container() function to access the DI\Container instance. This container is used to easily resolve classes.

use function OWC\ZGW\container;

container(): Di\Container

View the documentation of the PHP-DI container.

WordPress integration

This package offers a WordPress settings page integration. With it, clients can be configured by filling in some fields. View the WordPress documentation.

Endpoints

We've added our client(s). Now lets access an endpoint

Endpoints

The ZGW standard has several endpoints which can be accessed. This will show you how to access them. We'll be using OpenZaak with the 'zaken' endpoint in this example, but it can be exchanged with any of the supported ZGW clients or endpoints.

Accessing endpoints

The easiest way to access any endpoint is through a Client instance. All (supported) endpoints are available as a method on the Client class. For example:

use function OWC\ZGW\ApiClient;

$openzaakClient = apiClient('my-oz-client');

$zakenEndpoint = $openzaakClient->zaken();

Available endpoints

At the time of writing, the following endpoints are available to most (but not all!) ZGW clients. Remember: the endpoints are available as methods on a client instance.

📥 ZRC 🗂️ ZTC 📄 DRC
zaken zaaktypen objectinformatieobjecten
statussen statustypen enkelvoudiginformatieobjecten
rollen roltypen
resultaten catalogussen
zaakeigenschappen resultaattypen
zaakinformatieobjecten informatieobjecttypen
zaakobjecten eigenschappen

All of these endpoints are callable as a method on your client. It will return an subtype of the OWC\ZGW\Endpoints\Endpoint class.

$zakenEndpoint = $openzaakClient->zaaktypen();
$zakenEndpoint = $openzaakClient->objectinformatieobjecten();
$zakenEndpoint = $openzaakClient->catalogussen();
// etc.

Endpoint support

Not every ZGW client supports every endpoint, so it's a good habit to check for its support:

if ($openzaakClient->supports('zaken')) {
    // here be magic
}

Requesting entities

Most endpoints support three basic operations: all(), filter() and get().

All entities

Request all entities through the all() method:

$zakenEndpoint = $openzaakClient->zaken();

$zaken = $zakenEndpoint->all();

The result will be a OWC\ZGW\Support\PagedCollection (read more about collections).

Single entity

Request a single entity through the get() method:

$zakenEndpoint = $openzaakClient->zaken();

$zaak = $zakenEndpoint->get('unique-identifier-here');

The result will be a OWC\ZGW\Entities\Entity (read more about entities).

Filtering entities

Request entities which match a given filter.

$filteredZaken = $zakenEndpoint->filter($filter);

The $filter has to be of type OWC\ZGW\Endpoints\Filter\AbstractFilter. This will give any filter a few basic operations:

use OWC\ZGW\Endpoints\Filter\ZakenFilter;

$filter = new ZakenFilter();

// Add any parameter
$filter->add('myparameter', 'myvalue');

// Check if it exists
$filter->has('myparameter', 'myvalue');

// Or remove it
$filter->remove('myparameter');

All endpoints have their own filter implementation with their own methods, in respect to that endpoint. For example the ZakenFilter will have a method to add a BSN-number filter:

use OWC\ZGW\Endpoints\Filter\ZakenFilter;

$filter = new ZakenFilter();
$filter->byBsn('111222333');

$zakenByBsnNumber = $zakenEndpoint->filter($filter);

Other methods

Other endpoints might support different methods. Check the technical docs to see which endpoint supports what method.

Collections and entities

Most operations on an endpoint either return an Entity or a Collection.

WordPress

This package offers a WordPress settings page integration. With it, clients can be configured by filling in some fields.

Setup

This integration requires the CMB2 plugin. Make sure you install it before you continue.

After installation, two service providers have to be registered. The SettingsProvider class adds the settings page to WordPress. The ClientProvider automatically loads configured clients into the ApiClientManager.

It is recommended to register the service providers inside the plugins_loaded hook.

use OWC\ZGW\ApiClientManager;
use OWC\ZGW\WordPress\ClientProvider;
use OWC\ZGW\WordPress\SettingsProvider;

add_action('plugins_loaded', function () {
    $manager = new ApiClientManager();
    $manager->container()->get(SettingsProvider::class)->register();
    $manager->container()->get(ClientProvider::class)->register();
});

After this, you'll be able to access the settings page. It's located in the submenu of 'Settings' and is called 'ZGW API instellingen'.

Settings page example

Two settings are notable:

  1. Register naam: A unique(!) name for this client. This name is used when resolving it.
  2. Register versie: The supported version of the registry. ZGW 1.5.0 and later have support for the 'expand' functionality

After you've added the settings, the client can be resolved by it's name:

use function OWC\ZGW\apiClientManager;

$client = apiClientManager()->getClient('my-oz-register');
Clone this wiki locally