Installation — PHP

Le paquet mitoera/php-sdk expose la même arborescence de sous-clients que le SDK JavaScript, avec des objets de réponse typés.

Prérequis

• PHP ≥ 8.1
• Extensions curl et json
• Aucune dépendance Composer — le transport est du cURL natif, ni Guzzle ni PSR-18

Installer

composer require mitoera/php-sdk:^1.0

Version courante : v1.0.1, licence MIT. Rien d'autre à déclarer — le paquet est référencé sur Packagist, et la contrainte ^1.0 récupère les correctifs.

Ou directement dans le composer.json :

{
  "require": {
    "mitoera/php-sdk": "^1.0"
  }
}

Initialiser le client

use Mitoera\Sdk\MitoeraClient;

$client = new MitoeraClient([
    'keyId'  => getenv('MITOERA_KEY_ID'),   // pk_live_… ou pk_test_…
    'secret' => getenv('MITOERA_SECRET'),   // sk_…
]);

Options du constructeur

Option	Type	Défaut	Description
keyId	string	—	Identifiant de clé. Requis
secret	string	—	Secret de la clé. Requis
baseUrl	string	https://api.mitoera.com	Utile pour pointer une instance locale
timeout	int	30	Timeout HTTP en secondes

Omettre keyId ou secret lève une AuthException dès la construction — l'erreur se voit au démarrage, pas au premier appel.

L'environnement se déduit du préfixe de la clé : pk_test_ → sandbox, pk_live_ → production. L'URL, elle, ne change pas.

Vérifier que ça marche

$charts = $client->charts->listAll();
printf("%d plan(s) dans le workspace\n", count($charts));

Gérer les erreurs

use Mitoera\Sdk\Exception\ApiException;
use Mitoera\Sdk\Exception\AuthException;

try {
    $client->holds->hold($eventId, ['A-1'], $holdToken);
} catch (AuthException $e) {
    // Clé absente, invalide ou révoquée
} catch (ApiException $e) {
    $e->statusCode;      // ex. 409 sur un refus de siège
    $e->getMessage();    // « One or more seats are not available »
}

Hiérarchie

AuthException  ⟶  ApiException  ⟶  MitoeraException  ⟶  RuntimeException

Depuis la v1.0.1, un 401 ou un 403 lève une AuthException plutôt qu'une ApiException générique — et AuthException hérite d'ApiException.

L'ordre des catch compte

AuthException étant une ApiException, un catch (ApiException $e) placé en premier intercepte aussi les erreurs d'authentification et rend le catch (AuthException $e) suivant inatteignable. Toujours du plus spécifique au plus général, comme dans l'exemple ci-dessus.

statusCode porte le code HTTP, sauf pour les erreurs de configuration détectées avant tout appel réseau — keyId ou secret manquant — où il vaut 0.

Quand l'API renvoie un 401 au corps vide, c'est le SDK qui enrichit le message de l'exception : il rappelle la requête (GET https://api.mitoera.com/api/charts) et le préfixe de la clé utilisée, avec son mode. Seul le préfixe pk_test_ / pk_live_ y figure — ni le keyId complet, ni le secret ne sont repris, y compris dans vos logs.

Intégration Symfony

Déclarez le client comme service, avec les clés en variables d'environnement :

# config/services.yaml
services:
    Mitoera\Sdk\MitoeraClient:
        arguments:
            $options:
                keyId: '%env(MITOERA_KEY_ID)%'
                secret: '%env(MITOERA_SECRET)%'

Puis injectez-le où vous en avez besoin :

final class ReservationController extends AbstractController
{
    public function __construct(
        private readonly MitoeraClient $mitoera,
    ) {}

    #[Route('/reservation/{slug}', methods: ['GET'])]
    public function page(string $slug): Response
    {
        $event   = $this->mitoera->events->findByIdentifier($slug);
        $session = $this->mitoera->sessions->create($event->id);

        // Le holdToken reste côté serveur ; seul le sessionToken part au navigateur
        $this->requestStack->getSession()->set('mitoera_hold', $session->holdToken);

        return $this->render('reservation.html.twig', [
            'eventId'      => $event->id,
            'sessionToken' => $session->sessionToken,
        ]);
    }
}

Exemple complet — confirmer après paiement

use Mitoera\Sdk\Exception\ApiException;

public function confirmer(Request $request): JsonResponse
{
    $seatKeys  = $request->toArray()['seats'];
    $eventId   = $request->toArray()['eventId'];
    $holdToken = $request->getSession()->get('mitoera_hold');

    try {
        $book = $this->mitoera->holds->book($eventId, $seatKeys, $holdToken);
    } catch (ApiException $e) {
        if ($e->statusCode === 409) {
            return $this->json(['error' => 'Un siège vient d\'être pris'], 409);
        }
        throw $e;
    }

    return $this->json([
        'seats'    => $book->bookedSeats,
        'bookedAt' => $book->bookedAt->format(DATE_ATOM),
    ]);
}

Suite

• Client serveur — toutes les méthodes et leurs retours
• Widget par CDN — la partie navigateur, à coupler avec ce back-end
• Holds et sessions — le cycle de vie complet d'un panier