README

Composable PHP toolkit for the Zitadel identity provider. Part of the Oihana PHP ecosystem, this package bundles an OIDC/OAuth2 API client, JWT/JWKS verification, ArangoDB-backed session lifecycle helpers, OAuth client metadata resolution, V2 Action webhook catalog and descriptor, and Symfony Console commands.

📚 Documentation

Full API reference (generated with phpDocumentor): https://bcommebois.github.io/oihana-php-zitadel

User guides (FR + EN) live under wiki/.

📦 Installation

Requires PHP 8.4+ and a Zitadel instance reachable over HTTPS. Install via Composer:

composer require oihana/php-zitadel

✨ What you can do

• Talk to Zitadel over the Management + Auth APIs through ZitadelClient — a Guzzle-based HTTP client composed of focused traits (ZitadelClientApplicationTrait, ZitadelClientPasswordTrait, ZitadelClientRoleTrait, ZitadelClientServiceTrait, ZitadelClientSessionTrait, ZitadelClientTargetTrait, ZitadelClientUserTrait), with typed enums for endpoints, scopes, grants, query methods, error ids and outcomes.
• Resolve OAuth clients to human-readable names via OAuthClientResolver — in-process TTL cache + ArangoDB oauth_clients mirror + fallback to the Zitadel Management API for auto-seeding.
• Mirror Zitadel sessions in ArangoDB via SessionCreatorTrait — upsert on [identifier, clientId, userAgent, active], sid anchoring from the id-token claims, IP + User-Agent capture, first-login activation + pending invitation acceptance.
• Build V2 Action webhook handlers via ZitadelWebhookDescriptor + ZitadelWebhookCatalog — typed event keys, route declaration, secret rotation, validation.
• Plug into a CLI through the included ZitadelWebhookCommand — declarative webhook synchronization between Zitadel and the application.

Under the hood

• A consistent set of typed enums and constants — ZitadelEndpoint, ZitadelEndpointPlaceholder, ZitadelScope, ZitadelGrant, ZitadelQueryMethod, ZitadelError, ZitadelErrorId, ZitadelOutcome, ZitadelSessionField, ZitadelSessionSearchParam, ZitadelMessageKeyword, ZitadelOutput, ZitadelAppAuthMethod, ZitadelCookie — no magic strings.
• Pure-PHP HTTP transport based on GuzzleHttp v7.
• JWT/JWKS verification through firebase/php-jwt v7.
• Persistence delegated to oihana/php-arango for OAuth client mirror + session storage.

✅ Running tests

Run all tests:

composer test

Run a specific test file:

composer test ./tests/oihana/zitadel/webhooks/ZitadelWebhookDescriptorTest.php

The unit tests cover the OAuth client resolver, the session creator trait (with a PSR-7 mocked request), the webhook catalog and descriptor, the webhook command, error ids and selected client traits — they run without a live Zitadel instance.

🛠️ Generate the documentation

We use phpDocumentor to generate documentation into the ./docs folder.

composer doc

🧾 License

Licensed under the Mozilla Public License 2.0 (MPL‑2.0).

👤 About the author

• Author: Marc ALCARAZ (aka eKameleon)
• Email: marc@ooop.fr
• Website: https://www.ooop.fr

🔗 Related packages