API

L'attribut Api permet de créer facilement des routes d'API REST personnalisées dans WordPress, accessibles via /wp-json.

Utilisation de base

app/Controllers/MyController.php

use Elementum\Attributes\Api;

class MyController extends Controller
    #[Api(
        namespace: 'elementum/v1',
        endpoint: '/hello',
        methods: 'GET',
        params: [
            'name' => 'string',
            'age' => 'number'
        ]
    )]
    public function helloEndpoint($params, \WP_REST_Request $request)
    {
        return [
            'message' => sprintf('Bonjour %s ! Vous avez %d ans.',
                ucfirst($params['name']),
                $params['age']
            )
        ];
    }
}

// URL générée : /wp-json/elementum/v1/hello/Thibault/29
// Les paramètres sont passés dans l'URL, dans l'ordre de leur définition
// Premier paramètre (name) : /Thibault
// Deuxième paramètre (age) : /29

Paramètres de la méthode

Chaque méthode de contrôleur annotée avec #[Api] reçoit deux arguments :

Argument	Type	Description
$params	array	Paramètres d'URL (route params + query string) fusionnés par WP_REST_Request::get_params()
$request	\WP_REST_Request	Objet requête WP REST complet — accès au body, aux fichiers, aux headers, etc.

public function myEndpoint(array $params, \WP_REST_Request $request): array
{
    // Paramètres POST (multipart/form-data ou application/x-www-form-urlencoded)
    $body  = $request->get_body_params();

    // Fichiers uploadés (équivalent $_FILES)
    $files = $request->get_file_params();

    // Corps JSON brut (application/json)
    $json  = $request->get_json_params();

    return ['ok' => true];
}

Multipart & fichiers

Pour les formulaires avec fichiers (multipart/form-data), utilisez $request->get_body_params() pour les champs texte et $request->get_file_params() pour les fichiers. $params ne contient pas les données du corps POST.

Réponse

La méthode doit retourner un tableau qui sera automatiquement converti en JSON :

{
    "message": "Bonjour Thibault ! Vous avez 29 ans."
}

Paramètres

Paramètres obligatoires

namespace

• Type : string
• Description : Namespace de l'API (première partie de l'URL après /wp-json)
• Exemple : 'elementum/v1'

Paramètres optionnels

endpoint

• Type : string
• Défaut : '/'
• Description : Chemin de l'endpoint (deuxième partie de l'URL après le namespace)

name

• Type : string
• Description : Nom unique identifiant la route
• Remarque : Utile pour les références internes et les filtres

methods

• Type : string|array
• Défaut : 'GET'
• Description : Méthode(s) HTTP acceptée(s)
• Valeurs possibles : 'GET', 'POST', 'PUT', 'DELETE', 'PATCH' ou un tableau de ces valeurs

params

• Type : array
• Défaut : []
• Description : Définition des paramètres attendus et de leur type
• Format : 'nom_parametre' => 'type'
• Types supportés : string, number, boolean, array, object

permission

• Type : boolean
• Défaut : false
• Description : Si true, l'utilisateur doit être authentifié

Exemples avancés

Avec plusieurs méthodes HTTP

#[Api(
    namespace: 'elementum/v1',
    endpoint: '/articles',
    methods: ['GET', 'POST']
)]
public function handleArticles(array $params, \WP_REST_Request $request): array
{
    if ($request->get_method() === 'GET') {
        // Récupérer les articles
        // GET /wp-json/elementum/v1/articles
        return get_posts(['post_type' => 'post']);
    }

    // Créer un article depuis le corps POST
    $body = $request->get_body_params();
    // POST /wp-json/elementum/v1/articles (données dans le corps)
    return ['created' => true, 'title' => $body['title'] ?? ''];
}

// GET /wp-json/elementum/v1/articles - Récupère la liste des articles
// POST /wp-json/elementum/v1/articles - Crée un nouvel article

Avec validation des paramètres

#[Api(
    namespace: 'elementum/v1',
    endpoint: '/user',
    params: [
        'id' => 'number',
        'email' => 'string',
        'is_admin' => 'boolean'
    ]
)]
public function getUser(array $params, \WP_REST_Request $request): array
{
    // Les paramètres d'URL sont automatiquement validés selon les types spécifiés
    return [
        'id' => $params['id'],
        'email' => $params['email'],
        'is_admin' => $params['is_admin']
    ];
}

// URL générée : /wp-json/elementum/v1/user/42/test@example.com/true
// Les paramètres sont passés dans l'ordre de leur définition :
// Premier paramètre (id) : /42
// Deuxième paramètre (email) : /test@example.com
// Troisième paramètre (is_admin) : /true

// Exemple avec cURL (GET) :
// curl https://votresite.com/wp-json/elementum/v1/user/42/test@example.com/true

// Pour les méthodes POST/PUT, les paramètres peuvent aussi être passés dans le corps de la requête :
// curl -X POST https://votresite.com/wp-json/elementum/v1/user \
//   -H 'Content-Type: application/json' \
//   -d '{"id": 42, "email": "test@example.com", "is_admin": true}'

Bonnes pratiques

• Nommage : Utilisez des noms de méthodes descriptifs qui reflètent l'action de l'endpoint
• Documentation : Commentez le but de chaque endpoint et ses paramètres
• Validation : Profitez du système de typage des paramètres pour une validation automatique
• Sécurité : Utilisez le paramètre permission pour protéger les routes sensibles