tugrul/apigen

Generate REST API SDK libraries from annotated PHP interfaces. PSR-18 based, attribute-driven.

v1.0.0 2026-02-25 00:09 UTC

Requires

• php: >=8.1
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.1 || ^2.0

Requires (Dev)

• nyholm/psr7: ^1.8
• phpunit/phpunit: ^10.0
• psr/simple-cache: ^3.0

Suggests

• psr/simple-cache: Required to use Psr16TokenCache for Redis/Memcached/APCu token storage

MIT

• generator
• rest
• api
• sdk
• attributes
• psr-18
• php8

README

Generate REST API SDK clients from annotated PHP interfaces.

Define your API surface as a PHP interface, decorate methods with attributes, run the generator — done. ApiGen handles URL building, parameter binding, body encoding, authentication, and response decoding. You bring the PSR-18 HTTP client of your choice.

// 1. Define
interface UserApi {
    #[GET('/users/{id}')]
    #[Returns('array')]
    public function getUser(#[Path] int $id): array;

    #[DELETE('/users/{id}')]
    public function deleteUser(#[Path] int $id): void;
}

// 2. Generate (once, at development time)
$gen = new StubGenerator(__DIR__ . '/Generated');
$gen->generate(UserApi::class);

// 3. Use
$client = ClientBuilder::create('https://api.example.com')
    ->withPsr18($httpClient, $psr17, $psr17, $psr17)
    ->withBearerToken('my-token')
    ->build();

$api  = new UserApiImpl($client);
$user = $api->getUser(42);
$api->deleteUser(42);

Requirements

Requirement	Version
PHP	≥ 8.1
psr/http-client	^1.0
psr/http-factory	^1.0
psr/http-message	^1.1 || ^2.0

Installation

composer require tugrul/apigen

Documentation

Topic	Description
Quick Start	Define → Generate → Use in 5 minutes
Attributes Reference	Every attribute, target, and parameter
Authentication	Built-in strategies, OAuth 2, custom auth
Code Generation	StubGenerator, naming strategies, PSR-4 paths
CLI Tool	apigen generate, apigen list, config files
Client Configuration	ClientBuilder, middleware, custom decoders
ProxyRegistry	Group multiple stubs under one object
Error Handling	ApiException, error table
Testing	Running tests, testing your own stubs
Architecture	Package structure, request lifecycle

Key Features

• Attribute-driven — HTTP verbs, path/query/header/body binding, auth, encoding, and response types are all declared with native PHP 8 attributes. No XML, no YAML, no code to write beyond the interface.
• PSR-18 transport — bring your own HTTP client. Guzzle, Symfony HttpClient, Buzz, or any PSR-18 implementation.
• Pluggable auth — Bearer token, API key, Basic, HMAC, OAuth 2 client credentials, or your own AuthStrategy. Per-endpoint overrides with #[UseAuth].
• OAuth 2 token caching — in-memory, PHP session, filesystem, or any PSR-16 store (Redis, Memcached, APCu). Auto-refresh with configurable leeway.
• Five naming strategies — control the generated class name and output namespace. Default, Suffix, Sub-namespace, Callable, and per-interface Map.
• PSR-4 aware output paths — reads composer.json to compute the correct subdirectory offset, avoiding double-nesting of namespace roots.
• CLI tool — apigen generate and apigen list commands with config file support.
• Middleware — chain pre/post request hooks for logging, retry, rate-limiting, and more.

At a Glance

┌─────────────────────────────────────────────────────────────┐
│  Your PHP Interface  +  Attributes                          │
│        ↓  (apigen generate)                                 │
│  Generated Stub Class  (concrete, final, PSR-18 backed)     │
│        ↓                                                    │
│  ClientBuilder → DefaultSdkClient → PSR-18 HTTP Client      │
└─────────────────────────────────────────────────────────────┘

License

MIT