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

Package	Description
oihana/php-arango	Composable toolkit for ArangoDB — document/edge models, AQL helpers, controllers.
oihana/php-auth	Casbin RBAC + JWT/OIDC authorization toolkit.
oihana/php-commands	Symfony Console kernel and reusable command traits.
oihana/php-core	Core helpers and utilities shared across the ecosystem.
oihana/php-enums	Typed constants and enums — no more magic strings.
oihana/php-files	File system helpers (paths, readers, writers).
oihana/php-http	HTTP helpers — client IP, cookies, route patterns.
oihana/php-reflect	Reflection and object hydration utilities.
oihana/php-schema	Schema.org constants and vocabulary.
oihana/php-system	Framework helpers — controllers, models, request handling.

oihana / php-zitadel

Maintainers

Package info

Statistics

Security