Structure

Apivalk highly focuses SRP and therefore is also in generla designed to be like that. Controllers are invokable, you have a sepearte request and response

Structure and Usage in your projects

• SRP (Single Responsibility Principle): Each controller should handle exactly one route and one HTTP method.
• Immutable-like Responses: Response objects are designed to be built and returned, rather than modified in place across many layers.
• Container Integration: Apivalk supports PSR-11 containers, allowing for easy Dependency Injection in your controllers.
• Testing: The framework is built with testability in mind, utilizing interfaces and factories that are easily mockable.
• Automated Discovery: No manual route registration is required. The framework discovers your controllers and their metadata automatically.
• Fail Fast: Input is validated at the middleware level, before it ever reaches the controller, ensuring that your business logic only receives clean, typed data.

So, for example, let’s say our example is based up on a car store API.

• /yourfolder/Api/v1/Car/Controller/CreateController.php
• /yourfolder/Api/v1/Car/Request/CreateCarRequest.php
• /yourfolder/Api/v1/Car/Response/CreateCarResponse.php

Structure inside the Framework

1. Core Philosophy

Apivalk is built on several key architectural pillars designed to minimize boilerplate and maximize reliability.

See also: Request Lifecycle

Single Source of Truth (SSOT)

The defining feature of Apivalk is that documentation is code. Instead of writing separate documentation files or annotations, you define your API’s shape using PHP classes (AbstractProperty). This single definition drives:

• Input Population: Automatic extraction and type-casting of request data.
• Validation: Strict enforcement of data types, ranges, and patterns.
• Documentation Generation: Automatic creation of OpenAPI (Swagger) specifications and PHP DocBlocks for IDE support.

Type Safety

Even in PHP 7.2, Apivalk enforces strict type-safety through its Property system. Every incoming piece of data is validated against a schema before it ever reaches your controller.

Automated Discovery

Apivalk eliminates manual route registration. By using the ClassLocator, the framework discovers your controllers, reads their route metadata, and builds a high-performance routing cache automatically.

2. Project Structure

The project is organized into logical modules, each with a clear responsibility:

Documentation/

The heart of the framework. It contains the Property and Validator system.

• Property/: Definitions for String, Number, Boolean, Array, and Object properties.
• Validator/: Logic to validate raw data against Property definitions.
• OpenAPI/: Generators that transform Property schemas into OpenAPI 3.0 JSON.
• DocBlock/: Generators that create PHP DocBlocks for type-hinting Request objects.

Http/

The standard web layer.

• Request/: Abstractions for HTTP requests, divided into “Bags” (Header, Query, Path, Body, File).
• Response/: A suite of pre-defined response types (200, 400, 404, 500, etc.) ensuring consistent API output.
• Controller/: Base classes for your business logic.
• Method/: Typed representations of HTTP verbs.
• Renderer/: Handles the final conversion of Response objects to the output stream (defaulting to JSON).

Router/

Handles URI-to-Controller mapping and traffic control.

• Route Matching: Supports regex-based path parameters and HTTP method matching.
• Route Caching: Features a high-performance cache to avoid scanning classes on every request in production. Learn more
• Rate Limiting: Includes a built-in system to protect endpoints from abuse.
  • RateLimitInterface: The contract for defining limits.
  • RateLimiter: The engine that evaluates usage against the cache.
  • Learn more about Rate Limiting

Cache/

A generic caching layer used for performance optimization.

• CacheInterface: The base contract for all cache adapters.
• FilesystemCache: A disk-based implementation of the cache.
• CacheItem: A standardized object representing a cached entry, including TTL and creation metadata.
• Learn more about Cache

Middleware/

An “onion-style” pipeline where each middleware can inspect/modify the Request before passing it to the next layer or returning a Response early.

Security/

A robust, OpenAPI-compliant security and authorization system.

• AuthIdentity/: Objects representing the requester (e.g., JwtAuthIdentity, GuestAuthIdentity).
• Authenticator/: Services that turn credentials (like JWT) into an Identity (e.g., JwtAuthenticator).
• RouteAuthorization: Data carrier for security requirements on a route.
• Learn more about Security

Util/

Contains the ClassLocator, which is used for scanning namespaces and finding framework-compliant classes.

3. The Property & Validator System

The Property system is the engine that powers Apivalk.

1. Definition: You define a property (e.g., StringProperty) and configure its constraints (minLength, pattern, etc.).
2. Factory: ValidatorFactory creates the appropriate validator for that property.
3. Validation: The validator returns a ValidatorResult indicating success or specific error messages.

This system ensures that when you access $request->body()->get('email'), you are guaranteed that the data exists (if required) and matches your constraints.

4. Automation & Discovery

Apivalk is designed for developer productivity through automation:

1. Route Discovery: RouteCacheFactory uses ClassLocator to find all classes extending AbstractApivalkController. It calls getRoute() on each to build the routing table.
2. Request Population: AbstractApivalkRequest automatically populates itself using metadata from getDocumentation().
3. Request Validation: RequestValidationMiddleware automatically validates the populated request against the same documentation before the controller is invoked.