PHPackages                             obsidiane/auth-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. obsidiane/auth-sdk

ActiveSymfony-bundle[Authentication & Authorization](/categories/authentication)

obsidiane/auth-sdk
==================

Symfony bundle fournissant un client Obsidiane Auth orienté API (bridge + facades, Bearer token)

1.0.13(4mo ago)0139MITPHPPHP >=8.2

Since Nov 15Pushed 4mo agoCompare

[ Source](https://github.com/obsidiane-lab/auth-sdk)[ Packagist](https://packagist.org/packages/obsidiane/auth-sdk)[ RSS](/packages/obsidiane-auth-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (61)Used By (0)

Obsidiane Auth SDK for PHP
==========================

[](#obsidiane-auth-sdk-for-php)

SDK PHP orienté API pour consommer Obsidiane Auth avec une logique proche du SDK JS (bridge + facades). Authentification via Bearer token (optionnel), pas de cookies.

Features
--------

[](#features)

✅ **Bridge API-first** (get/getCollection/post/patch/put/delete + request) ✅ **Facades ressources** avec modèles hydratés via Symfony Serializer ✅ **JSON-LD par défaut** (`Accept: application/ld+json`) ✅ **Content-Type auto** (`POST/PUT: application/ld+json`, `PATCH: application/merge-patch+json`) ✅ **Exceptions structurées** via `ApiErrorException` sur erreurs HTTP ✅ **Configuration Symfony** simple et explicite

Installation
------------

[](#installation)

```
composer require obsidiane/auth-sdk
```

Configuration Symfony
---------------------

[](#configuration-symfony)

**config/bundles.php**

```
return [
    // ...
    Obsidiane\AuthBundle\ObsidianeAuthBundle::class => ['all' => true],
];
```

**config/packages/obsidiane\_auth.yaml**

```
obsidiane_auth:
  base_url: '%env(OBSIDIANE_AUTH_BASE_URL)%'
  token: '%env(OBSIDIANE_AUTH_TOKEN)%' # optionnel
  defaults:
    headers: { }
    timeout_ms: 10000 # optionnel
  debug: false
```

**.env**

```
OBSIDIANE_AUTH_BASE_URL=https://auth.example.com
OBSIDIANE_AUTH_TOKEN=your-static-bearer-token
```

Le `token` est optionnel : s'il est absent ou vide, aucun header `Authorization` n'est ajouté (utile pour les endpoints publics). `base_url` est requis et peut inclure ou non `/api` selon votre usage (adaptez vos routes en conséquence).

Utilisation
-----------

[](#utilisation)

### FacadeFactory (ressources)

[](#facadefactory-ressources)

```
use Obsidiane\AuthBundle\Bridge\FacadeFactory;

final class UsersService
{
    public function __construct(
        private readonly FacadeFactory $factory,
    ) {}

    public function listUsers(): array
    {
        $users = $this->factory->create('/api/users', \App\Dto\UserRead::class);
        $result = $users->getCollection();

        return $result->items; // list
    }
}
```

### BridgeFacade (endpoints custom)

[](#bridgefacade-endpoints-custom)

```
use Obsidiane\AuthBundle\Bridge\BridgeFacade;

final class AuthService
{
    public function __construct(
        private readonly BridgeFacade $bridge,
    ) {}

    public function me(): array
    {
        return $this->bridge->get('/api/auth/me');
    }
}
```

### Requête custom avec `HttpRequestConfig`

[](#requête-custom-avec-httprequestconfig)

```
use Obsidiane\AuthBundle\Bridge\Http\HttpRequestConfig;

$req = new HttpRequestConfig(
    method: 'GET',
    url: '/api/users',
    query: ['page' => 1, 'itemsPerPage' => 20],
    headers: ['X-Request-ID' => 'req_123'],
    timeoutMs: 5000,
);

$response = $bridge->request($req);
```

Hydratation des modèles
-----------------------

[](#hydratation-des-modèles)

Les facades utilisent `Symfony\Component\Serializer\Normalizer\NormalizerInterface` et `DenormalizerInterface` pour la sérialisation/désérialisation. Les modèles du SDK exposent `@id` via la propriété `$iri`. Si vous utilisez vos propres modèles, mappez `@id` avec `#[SerializedName('@id')]`.

**Note technique** : Le SDK nécessite que le `SerializerInterface` implémente aussi `NormalizerInterface` et `DenormalizerInterface` (ce qui est le cas avec le Serializer standard de Symfony). Le `FacadeFactory` vérifie automatiquement ces interfaces au runtime.

API publique
------------

[](#api-publique)

### Classes principales

[](#classes-principales)

- **`BridgeFacade`** : appels HTTP bas niveau (GET, GET collection, POST, PUT, PATCH, DELETE, request)
- **`FacadeFactory`** : création de `ResourceFacade` avec hydratation automatique
- **`ResourceFacade`** : CRUD + collections hydratées (generic type-safe)
- **`Collection`** : items + metadata JSON-LD (`totalItems`, `id`, `type`, `context`, `view`, `search`)

### Modèles

[](#modèles)

Les modèles exposent les propriétés JSON-LD standard :

- `Item` : classe de base avec `$iri` (`@id`), `$type` (`@type`), `$context` (`@context`)
- Tous les modèles générés héritent de `Item` ou exposent ces propriétés

### Paramètres de configuration

[](#paramètres-de-configuration)

#### Clés principales

[](#clés-principales)

- `base_url` : URL de base du service Auth (requis).
- `token` : Bearer token optionnel, ajouté si non vide.
- `debug` : active les logs debug du bridge HTTP.

#### `defaults` (dans `obsidiane_auth.yaml`)

[](#defaults-dans-obsidiane_authyaml)

- `headers`: headers HTTP appliqués à toutes les requêtes (peuvent être surchargés par appel)
- `timeout_ms`: timeout en millisecondes (par défaut: aucun)

#### Options par requête

[](#options-par-requête)

Toutes les méthodes de `ResourceFacade` et `BridgeFacade` acceptent un paramètre `HttpCallOptions` optionnel :

```
use Obsidiane\AuthBundle\Bridge\Http\HttpCallOptions;

$options = new HttpCallOptions(
    headers: ['X-Custom-Header' => 'value'],
    timeoutMs: 5000, // en ms
    responseType: 'text',
);

$users->getCollection([], $options);
```

`responseType: 'text'` retourne la réponse brute (string). Par défaut, la réponse est décodée en JSON.

Exemples avancés
----------------

[](#exemples-avancés)

### Filtrage et pagination

[](#filtrage-et-pagination)

```
$users = $factory->create('/api/users', UserRead::class);

// Pagination
$result = $users->getCollection([
    'page' => 2,
    'itemsPerPage' => 10,
]);

// Filtres
$result = $users->getCollection([
    'filters' => [
        'email' => 'user@example.com',
        'role' => 'ROLE_ADMIN',
    ],
]);

// Metadata
echo $result->totalItems;  // Nombre total d'items
echo $result->id;          // IRI de la collection (@id)
```

### Headers personnalisés

[](#headers-personnalisés)

```
use Obsidiane\AuthBundle\Bridge\Http\HttpCallOptions;

$options = new HttpCallOptions(
    headers: [
        'X-Request-ID' => uniqid(),
        'Accept-Language' => 'fr-FR',
    ],
);

$user = $users->get('/api/users/1', $options);
```

### Gestion d'erreurs

[](#gestion-derreurs)

```
use Obsidiane\AuthBundle\Exception\ApiErrorException;

try {
    $user = $users->get('/api/users/999');
} catch (ApiErrorException $e) {
    // Erreur HTTP (404, 500, etc.)
    error_log($e->getMessage());
    error_log('Status code: ' . $e->getStatusCode());
    error_log('Error code: ' . $e->getErrorCode());
}
```

`ApiErrorException` expose aussi `getDetails()` et `getPayload()` pour inspecter la réponse.

### Codes d’erreur (API)

[](#codes-derreur-api)

Statuts HTTP exposés par l’API Auth :

HTTPCas principauxDétails400Requête invalide, token invalide`verify-email` (id manquant), reset/verify token invalide, invitation sans token (`details.token = INVALID_INVITATION`).401Non authentifié`me`, JWT invalide/expiré, service token invalide, login refusé.403Accès refuséOrigin/Referer non autorisé, endpoints admin sans rôle.404IntrouvableInvitation inconnue, user introuvable, inscription désactivée.409ConflitEmail déjà utilisé, invitation déjà acceptée, bootstrap requis ou déjà fait.410ExpiréInvitation expirée, lien de vérification expiré, reset token expiré.422ValidationEmail/mot de passe invalides, champs requis, `INVALID_ROLES`, confirmation mot de passe.423VerrouilléEmail non vérifié lors du login.429Rate limitLogin, register, invite, invite/complete, password/forgot/reset, setup/admin.500Erreur interneÉchec de reset password non géré (`ResetRequestFailedException`).503Service indisponibleÉchec d’envoi d’email (`MailDispatchException`).Identifiants d’erreurs utiles dans les payloads/validations :

- `INVALID_INVITATION`
- `INVALID_ROLES`

### Invitation (règles métiers)

[](#invitation-règles-métiers)

- Un utilisateur **déjà vérifié** ne peut pas être ré-invité.
- Un utilisateur **non vérifié** peut être ré-invité : l’email est renvoyé si l’invitation est encore valide, sinon elle est régénérée.

Qualité du code
---------------

[](#qualité-du-code)

Le SDK maintient une qualité de code stricte :

- ✅ **PHPStan Level 6** : Zero erreur d'analyse statique
- ✅ **Types stricts** : `declare(strict_types=1)` dans tous les fichiers
- ✅ **Generics** : `ResourceFacade`, `Collection` pour type-safety
- ✅ **Readonly** : Classes immuables avec `readonly`
- ✅ **PSR-12** : Standard de code PHP

Troubleshooting
---------------

[](#troubleshooting)

### Erreur "Serializer must implement NormalizerInterface"

[](#erreur-serializer-must-implement-normalizerinterface)

Si vous obtenez cette erreur, assurez-vous que votre `SerializerInterface` est bien le Serializer standard de Symfony (pas un mock ou une implémentation custom sans normalizer).

### Timeout des requêtes

[](#timeout-des-requêtes)

Par défaut, aucun timeout n'est appliqué. Pour en définir un :

```
# config/packages/obsidiane_auth.yaml
obsidiane_auth:
  defaults:
    timeout_ms: 30000  # 30 secondes
```

Ou par requête :

```
use Obsidiane\AuthBundle\Bridge\Http\HttpCallOptions;

$options = new HttpCallOptions(timeoutMs: 30000);
$result = $users->getCollection([], $options);
```

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance76

Regular maintenance activity

Popularity10

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity61

Established project with proven stability

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

59

Last Release

134d ago

Major Versions

0.1.52 → 1.0.22026-01-04

### Community

Maintainers

![](https://www.gravatar.com/avatar/d452e74fd96dc62de2f7fdc3a22e63c4f5d0a6d3eafcceb75a68a45425d51cf1?d=identicon)[obsidiane](/maintainers/obsidiane)

### Embed Badge

![Health badge](/badges/obsidiane-auth-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/obsidiane-auth-sdk/health.svg)](https://phpackages.com/packages/obsidiane-auth-sdk)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[simplesamlphp/simplesamlphp

A PHP implementation of a SAML 2.0 service provider and identity provider.

1.1k12.4M193](/packages/simplesamlphp-simplesamlphp)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

50570.7k1](/packages/web-auth-webauthn-framework)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)