README

final class CustomAuthContext implements AuthenticationContext {
    public function __construct(
        public readonly string|null $authenticatedUserId,
    ) {
    }
}

#[Description('Unique handle for a user in the API')]
#[StringBased(minLength: 1, maxLength: 200)]
final class Username {
    private function __construct(
        public readonly string $value,
    ) {
    }

    public static function fromString(string $value): self {
        return instantiate(self::class, $value);
    }
}

#[Description('Email address of a user')]
#[StringBased(format: StringTypeFormat::email)]
final class EmailAddress {
    private function __construct(
        public readonly string $value,
    ) {
    }

    public static function fromString(string $value): self {
        return instantiate(self::class, $value);
    }
}

final class User {

    public function __construct(
        public readonly Username $username,
        public readonly EmailAddress $emailAddress,
    ) {
    }
}

/**
 * @implements IteratorAggregate<User>
 */
#[Description('A set of users')]
#[ListBased(itemClassName: User::class)]
final class Users implements IteratorAggregate
{
    /**
     * @param array<User> $users
     */
    private function __construct(private readonly array $users) {
    }

    public static function fromArray(array $users): self {
        return instantiate(self::class, $users);
    }

    public function getIterator(): Traversable {
        yield from $this->users;
    }
}

final class AddUser {
    public function __construct(
        public readonly Username $username,
        public readonly EmailAddress $emailAddress,
    ) {
    }
}

interface UserRepository {
    public function findAll(): Users;
    public function findByUsername(Username $username): User|null;
    public function add(User $user): void;
}

#[OpenApi(apiTitle: 'Some API', apiVersion: '1.2.3', openApiVersion: '3.0.3', contact: ['name' => 'Contact Name', 'url' => 'https://contact-url.example.com', 'email' => 'contact@example.com'], license: ['name' => 'License name', 'id' => 'licenseId', 'url' => 'https://license.example.com'], securitySchemes: ['basicAuth' => ['type' => 'http', 'scheme' => 'basic', 'description' => 'Basic authentication']])]
#[Description('Some API description')]
final class SomeApi
{

    public function __construct(
        private readonly UserRepository $userRepository,
    ) {
    }

    #[Operation(path: '/users', method: 'GET', summary: 'Get Users')]
    #[Description('Retrieves all users from the repository')]
    public function users(): Users
    {
        return $this->userRepository->findAll();
    }

    #[Operation(path: '/users/{username}', method: 'GET', summary: 'Get a single user by its username')]
    #[Description('Retrieves a single user or returns a 404 response if not found')]
    public function userByUsername(Username $username): User|NotFoundResponse
    {
        return $this->userRepository->findByUsername($username) ?: new NotFoundResponse();
    }

    #[Operation(path: '/users', method: 'POST', summary: 'Add a new user', security: 'basicAuth')]
    #[Description('Saves a new user to the repository')]
    public function addUser(AddUser $command, CustomAuthContext $authContext): CreatedResponse|UnauthorizedResponse
    {
        if ($authContext->authenticatedUserId !== 'john.doe') {
            return new UnauthorizedResponse();
        }
        $this->userRepository->add(new User($command->username, $command->emailAddress));
        return new CreatedResponse();
    }
}

$generator = new OpenApiGenerator();
$openApiObject = $generator->generate(SomeApi::class, OpenApiGeneratorOptions::create());
assert($openApiObject instanceof OpenApiObject);
$expectedSchema = <<<'JSON'
{"openapi":"3.0.3","info":{"title":"Some API","version":"1.2.3","description":"Some API description","contact":{"name":"Contact Name","url":"https:\/\/contact-url.example.com","email":"contact@example.com"},"license":{"name":"License name","url":"https:\/\/license.example.com"}},"paths":{"\/users":{"get":{"summary":"Get Users","description":"Retrieves all users from the repository","operationId":"users","responses":{"200":{"description":"Default","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Users"}}}}}},"post":{"summary":"Add a new user","description":"Saves a new user to the repository","operationId":"addUser","requestBody":{"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AddUser"}}},"required":true},"responses":{"201":{"description":"Created"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"basicAuth":[]}]}},"\/users\/{username}":{"get":{"summary":"Get a single user by its username","description":"Retrieves a single user or returns a 404 response if not found","operationId":"userByUsername","parameters":[{"name":"username","in":"path","required":true,"schema":{"$ref":"#\/components\/schemas\/Username"}}],"responses":{"200":{"description":"Default","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/User"}}}},"400":{"description":"Bad Request"},"404":{"description":"Not Found"}}}}},"components":{"schemas":{"Username":{"type":"string","description":"Unique handle for a user in the API","minLength":1,"maxLength":200},"EmailAddress":{"type":"string","description":"Email address of a user","format":"email"},"User":{"type":"object","properties":{"username":{"$ref":"#\/components\/schemas\/Username"},"emailAddress":{"$ref":"#\/components\/schemas\/EmailAddress"}},"additionalProperties":false,"required":["username","emailAddress"]},"Users":{"type":"array","description":"A set of users","items":{"$ref":"#\/components\/schemas\/User"}},"AddUser":{"type":"object","properties":{"username":{"$ref":"#\/components\/schemas\/Username"},"emailAddress":{"$ref":"#\/components\/schemas\/EmailAddress"}},"additionalProperties":false,"required":["username","emailAddress"]}},"securitySchemes":{"basicAuth":{"type":"http","description":"Basic authentication","scheme":"basic"}}}}
JSON;
assert(json_encode($openApiObject) === $expectedSchema);

// ...
final class FakeUserRepository implements UserRepository {

    /**
     * @var array<string, User>
     */
    private array $usersByUsername;

    public function __construct()
    {
        $this->usersByUsername = [
            'john.doe' => new User(Username::fromString('john.doe'), EmailAddress::fromString('john.doe@example.com')),
            'jane.doe' => new User(Username::fromString('jane.doe'), EmailAddress::fromString('jane.doe@example.com')),
        ];
    }

    public function findAll(): Users {
        return Users::fromArray(array_values($this->usersByUsername));
    }

    public function findByUsername(Username $username): User|null
    {
        return $this->usersByUsername[$username->value] ?? null;
    }

    public function add(User $user): void
    {
        $this->usersByUsername[$user->username->value] = $user;
    }
}

final class AuthContextProvider implements AuthenticationContextProvider {
    public function getAuthenticationContext(ServerRequestInterface $request, SecurityRequirementObject $securityRequirement): CustomAuthContext|null {
        // TODO: evaluate the request and security requirement
        return new CustomAuthContext(authenticatedUserId: 'john.doe');
    }
}

$api = new SomeApi(new FakeUserRepository());
$httpFactory = new HttpFactory();
$requestHandler = new RequestHandler($api, $httpFactory, $httpFactory, authenticationContextProvider: new AuthContextProvider());

$request = ServerRequest::fromGlobals();
try {
    $response = $requestHandler($request);
} catch (RequestException $e) {
    $response = $httpFactory->createResponse($e::getStatusCode(), $e::getReasonPhrase());
    $response->getBody()->write($e->getMessage());
}
http_response_code($response->getStatusCode());
foreach ($response->getHeaders() as $k => $values) {
    foreach ($values as $v) {
        header(sprintf('%s: %s', $k, $v), false);
    }
}
echo $response->getBody();