README

Bibliothèque PHP pour créer des APIs REST automatiques, inspirée d'API Platform de Symfony.

Fonctionnalités

✅ Annotations pour exposer des entités en API
✅ Sérialisation JSON automatique avec groupes
✅ Opérations CRUD automatiques
✅ Advanced filtering system : SearchFilter, DateFilter, RangeFilter, BooleanFilter, OrderFilter
✅ Automatic sorting : Multi-column sorting via query parameters
✅ Automatic pagination : Support for page and limit parameters with metadata
✅ Automatic validation : Data validation with structured messages (RFC 7807)
✅ Standardized error handling : Problem Details format (RFC 7807)
✅ Relations support : Embedding and subresources for Doctrine relations
✅ Events system : Pre/post hooks integrated with core-php EventDispatcher
✅ Documentation Swagger/OpenAPI automatique
✅ Interface Swagger UI pour tester l'API
✅ Intégration avec le Core PHP existant

Installation

composer require julienlinard/php-api

Utilisation

1. Annoter une entité

use JulienLinard\Api\Annotation\ApiResource;
use JulienLinard\Api\Annotation\ApiProperty;
use JulienLinard\Doctrine\Mapping\Entity;
use JulienLinard\Doctrine\Mapping\Id;
use JulienLinard\Doctrine\Mapping\Column;

#[ApiResource(
    operations: ['GET', 'POST', 'PUT', 'DELETE'],
    routePrefix: '/api'
)]
#[Entity]
class User
{
    #[Id]
    #[Column(type: 'integer')]
    #[ApiProperty(groups: ['read', 'write'])]
    public ?int $id = null;

    #[Column(type: 'string', length: 255)]
    #[ApiProperty(groups: ['read', 'write'])]
    public string $email;

    #[Column(type: 'string', length: 255)]
    #[ApiProperty(groups: ['read'])] // Seulement en lecture
    public string $password;

    #[Column(type: 'string', length: 100)]
    #[ApiProperty(groups: ['read', 'write'])]
    public string $name;
}

2. Créer un contrôleur API

use JulienLinard\Api\Controller\ApiController;
use JulienLinard\Api\Serializer\JsonSerializer;

class UserController extends ApiController
{
    public function __construct()
    {
        parent::__construct(User::class, new JsonSerializer());
    }
}

3. Définir les routes

use JulienLinard\Router\Router;

$router = new Router();

// Routes automatiques pour l'API
$router->get('/api/users', [UserController::class, 'index']);
$router->get('/api/users/{id}', [UserController::class, 'show']);
$router->post('/api/users', [UserController::class, 'create']);
$router->put('/api/users/{id}', [UserController::class, 'update']);
$router->delete('/api/users/{id}', [UserController::class, 'delete']);

4. Ajouter la documentation Swagger (optionnel)

use JulienLinard\Api\Controller\SwaggerController;

// Créer le contrôleur Swagger avec vos entités
$swaggerController = new SwaggerController(
    entityClasses: [User::class, Product::class], // Liste des entités exposées
    title: 'Mon API',
    version: '1.0.0',
    basePath: '/api'
);

// Routes pour la documentation
$router->get('/api/docs', [$swaggerController, 'ui']);        // Interface Swagger UI
$router->get('/api/docs.json', [$swaggerController, 'json']);  // Spec OpenAPI JSON
$router->get('/api/docs.yaml', [$swaggerController, 'yaml']);  // Spec OpenAPI YAML

Accédez à /api/docs pour voir l'interface Swagger UI interactive où vous pouvez :

Voir toutes les entités exposées
Voir toutes les opérations disponibles (GET, POST, PUT, DELETE, PATCH)
Tester les requêtes directement dans le navigateur
Voir les schémas de données

Documentation

Voir README.fr.md pour la documentation complète en français.

julienlinard / php-api

Maintainers

Details