# Apivalk

## Docs

- [Filesystem & Custom Cache](https://docs.apivalk.com/cache/filesystem-cache.md): Learn how to use the built-in FilesystemCache or create your own custom cache implementation for high-scale environments.
- [Overview](https://docs.apivalk.com/cache/index.md): Apivalk features a generic, high-performance caching layer designed to optimize resource-intensive operations, such as automated route discovery and metadata processing.
- [Best OpenAPI/REST Practices](https://docs.apivalk.com/concepts/best-openapi-practices.md): Apivalk follows and introduces modern best practices for OpenAPI
- [Coding Standards](https://docs.apivalk.com/concepts/coding-standards.md): Apivalk follows modern PHP standards and clean code principles to ensure the framework remains lightweight, predictable, and easy to extend
- [Request Lifecycle](https://docs.apivalk.com/concepts/request-lifecycle.md): This page describes the lifecycle of an HTTP request within the Apivalk framework, from the initial entry point to the final response rendering
- [Structure](https://docs.apivalk.com/concepts/structure.md): 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
- [Configuration](https://docs.apivalk.com/configuration.md): Apivalk is configured via the `ApivalkConfiguration` class. This class holds the router, renderer, exception handler, and the optional PSR-11 container.
- [Contributing](https://docs.apivalk.com/contributing.md): Coming soon.
- [Error Handling](https://docs.apivalk.com/core/error-handling.md): Apivalk provides a centralized mechanism to handle unhandled exceptions, ensuring that your API always returns a predictable, structured response even when unexpected errors occur.
- [Events](https://docs.apivalk.com/core/events.md): Coming soon.
- [Customization](https://docs.apivalk.com/customization/customization.md): Apivalk is designed with a "Modular by Design" philosophy. Almost every core component of the framework can be replaced, extended, or reconfigured to suit your project's specific needs.
- [Deprecation & Upgrade](https://docs.apivalk.com/deprecating-upgrade.md)
- [Docblock Generator](https://docs.apivalk.com/documentation/docblock-generator.md): The `DocBlockGenerator` is a developer-experience (DX) tool that bridges the gap between your documentation definitions and your IDE. It provides full autocompletion for request properties that are otherwise handled via "magic" getters.
- [Overview](https://docs.apivalk.com/documentation/index.md): Apivalk is built on the philosophy of **Documentation-Driven Development**. This means that your API's documentation is not an afterthought, but the core engine that drives the framework.
- [OpenAPI Generator](https://docs.apivalk.com/documentation/openapi-generator.md): The `OpenAPIGenerator` is the component responsible for converting your code-based documentation into a standardized OpenAPI 3.0 (Swagger) specification.
- [Property](https://docs.apivalk.com/documentation/property.md): The Property System is the core metadata engine of Apivalk. It defines how data is structured, validated, and documented. Every property in your `getRequestDocumentation()` or `getResponseDocumentation()` is an instance of a class extending `AbstractProperty`.
- [Property Collection](https://docs.apivalk.com/documentation/property-collection.md): Property Collections in Apivalk are used to group multiple properties together. They serve as the backbone for `AbstractObjectProperty` and are essential for maintaining reusable data structures and managing different data "views" (modes).
- [Request](https://docs.apivalk.com/documentation/request.md): The `ApivalkRequestDocumentation` class is the primary container for defining the input contract of an API endpoint. It is returned by the static `getDocumentation()` method on your request class.
- [Response](https://docs.apivalk.com/documentation/response.md): The `ApivalkResponseDocumentation` class defines the structure of the data returned by an API endpoint. It is returned by the static `getDocumentation()` method on your response class.
- [Response Objects](https://docs.apivalk.com/documentation/response-objects.md): To maintain consistency across your API, Apivalk encourages the use of reusable response objects for common data structures like errors, pagination envelopes, or standard resource representations.
- [Authenticate with a custom API key header](https://docs.apivalk.com/how-to/api-key-auth.md): Swap the built-in bearer-token flow for an X-Api-Key header backed by your own lookup (database, KMS, static config, ...).
- [Authenticate, authorize, and inspect identity](https://docs.apivalk.com/how-to/auth.md): How the Apivalk auth pieces fit together: Authenticator → AuthIdentity → RouteAuthorization → Middleware. What the developer has to wire, and what happens automatically.
- [Model complex objects with PropertyCollection](https://docs.apivalk.com/how-to/complex-objects.md): When a request body or response carries nested objects or arrays of objects, compose them with AbstractPropertyCollection + AbstractObjectProperty + ArrayProperty. This keeps the OpenAPI schema and runtime validation in sync.
- [Configure Apivalk](https://docs.apivalk.com/how-to/configure.md): Bootstrap Apivalk end-to-end: router, middlewares, renderer, container, logger, and localization. The final section covers how to extend the configuration as your app grows.
- [Write a custom middleware](https://docs.apivalk.com/how-to/custom-middleware.md): Implement MiddlewareInterface, understand the onion execution order, and know when to choose middleware over a controller decorator.
- [Add filtering to a list endpoint](https://docs.apivalk.com/how-to/filtering.md): Declare typed filters on a route, validate client input automatically, and read the resolved values with the right PHP type inside your controller.
- [Generate OpenAPI and request docblocks](https://docs.apivalk.com/how-to/generate-openapi.md): A small PHP script that boots Apivalk, runs OpenAPIGenerator to write `openapi.json`, and runs DocBlockGenerator to emit IDE autocomplete shapes. Drop it in `bin/` and wire it to a CI step.
- [How-To Guides](https://docs.apivalk.com/how-to/index.md): Task-focused walkthroughs for the most common things you'll build with Apivalk. Each guide is self-contained and shows working code end-to-end.
- [Authenticate with JWT (JWKS)](https://docs.apivalk.com/how-to/jwt-auth.md): Wire up JwtAuthenticator against any OAuth2 / OIDC provider that exposes a JWKS endpoint — Auth0, Okta, Keycloak, Cognito, Azure AD, etc.
- [Build a full CRUD surface without resources](https://docs.apivalk.com/how-to/manual-crud.md): The explicit variant: four controllers, four requests, four responses for a single entity. Use this when you need full control over request/response shape, or the endpoints don't all map to the same payload.
- [Add pagination to a list endpoint](https://docs.apivalk.com/how-to/pagination.md): Pick a pagination strategy — page, offset, or cursor — and wire it end-to-end: route declaration, controller consumption, response envelope.
- [Build a public endpoint: GET /health](https://docs.apivalk.com/how-to/public-endpoint.md): The shortest possible Apivalk endpoint — no auth, no path params, no body. Useful as a Kubernetes liveness probe or a smoke test.
- [Add rate limiting](https://docs.apivalk.com/how-to/rate-limiting.md): Attach a rate limit to any route — per-IP by default — and let the middleware reject overages with 429 and emit the standard X-RateLimit-* response headers.
- [Build a CRUD surface with a resource (Animal)](https://docs.apivalk.com/how-to/resource-crud.md): Declare a resource once, pair it with five thin controller subclasses, and get Create/View/Update/Delete/List endpoints with request validation, OpenAPI schemas, filtering, sorting, and pagination — no request or response classes to author by hand.
- [Add sorting to a list endpoint](https://docs.apivalk.com/how-to/sorting.md): Declare the sortable fields on the route, let the framework validate `order_by`, and read the resolved SortBag in your controller.
- [Controller](https://docs.apivalk.com/http/controller.md): In Apivalk, controllers are the entry point for your business logic. Following the Single Responsibility Principle, each controller class should handle exactly one HTTP route and method.
- [Filtering](https://docs.apivalk.com/http/filtering.md): Apivalk provides built-in support for route-level filtering, allowing clients to narrow down results by specifying conditions on fields.
- [Overview](https://docs.apivalk.com/http/index.md): The HTTP layer in Apivalk provides a robust, type-safe, and structured way to handle the web request/response cycle. It bridges the gap between raw PHP superglobals and your business logic.
- [Localization](https://docs.apivalk.com/http/localization.md): Apivalk provides built-in locale resolution from the Accept-Language header, with BCP 47 compliant locale handling.
- [Pagination](https://docs.apivalk.com/http/pagination.md): Apivalk provides built-in support for different pagination types: Page, Offset, and Cursor. Pagination is defined at the route level and metadata is automatically injected into the request and response.
- [Request](https://docs.apivalk.com/http/request.md): Requests in Apivalk are strongly typed and self-validating. By defining a request class, you define the "shape" of the data your endpoint expects.
- [Response](https://docs.apivalk.com/http/response.md): Apivalk uses typed response objects to ensure consistent API output across your entire application.
- [Sorting](https://docs.apivalk.com/http/sorting.md): Apivalk provides built-in support for route-level sorting, allowing clients to specify how the results should be sorted.
- [Intro](https://docs.apivalk.com/index.md): The official home for everything related to Apivalk — your OpenAPI-first, framework-agnostic, and developer-centric API framework for PHP.
- [Installation](https://docs.apivalk.com/installation.md): Apivalk is a lightweight, framework-agnostic REST API framework for PHP. It can be installed easily via Composer.
- [Authentication Middleware](https://docs.apivalk.com/middleware/authentication.md): The Authentication Middleware is responsible for identifying the user making the request and populating the Request with an AuthIdentity.
- [Middleware](https://docs.apivalk.com/middleware/index.md): Middleware provides a convenient mechanism for filtering and intercepting HTTP requests entering your application. In Apivalk, middleware is executed in an "onion" style, where each middleware can perform actions before and after the subsequent middleware or the final controller.
- [Rate Limit Middleware](https://docs.apivalk.com/middleware/rate-limit.md): The `RateLimitMiddleware` enforces rate limiting rules defined on your routes. It tracks request frequency and returns a 429 Too Many Requests response when limits are exceeded.
- [Request Validation](https://docs.apivalk.com/middleware/request-validation.md): The `RequestValidationMiddleware` is a core component of Apivalk's Documentation-Driven Development approach. It ensures that every request hitting your controller strictly adheres to the schema defined in your `ApivalkRequestDocumentation`.
- [Sanitize](https://docs.apivalk.com/middleware/sanitize.md): The `SanitizeMiddleware` is a security-focused component designed to protect your application from Cross-Site Scripting (XSS) and other injection-style attacks by automatically escaping HTML characters in request parameters.
- [Security Middleware](https://docs.apivalk.com/middleware/security.md): The Security Middleware enforces scope-based authorization as defined in your OpenAPI route specifications.
- [REST API Standards Overview](https://docs.apivalk.com/open-api-best-practices/01-overview.md): Core principles and scope of REST API standards in Apivalk.
- [RESTful design and naming](https://docs.apivalk.com/open-api-best-practices/02-rest-design-and-naming.md): REST principles, HTTP methods, and naming conventions for routes, identifiers, and fields.
- [Versioning and resource structure](https://docs.apivalk.com/open-api-best-practices/03-versioning-and-structure.md): URL-based versioning and folder and resource organization guidelines.
- [Pagination, filtering, and sorting](https://docs.apivalk.com/open-api-best-practices/04-pagination-filtering-sorting.md): How to paginate, sort, and filter collections consistently.
- [Response format and status codes](https://docs.apivalk.com/open-api-best-practices/05-responses-errors-status-codes.md): Standard response envelopes, error objects, validation errors, and HTTP status codes.
- [Localization and internationalization](https://docs.apivalk.com/open-api-best-practices/06-localization-i18n.md): Standards for localized response messages and language negotiation.
- [Resource Controllers](https://docs.apivalk.com/resources/controllers.md): Five abstract controllers — Create, View, Update, Delete, List — turn an `AbstractResource` into a full CRUD surface.
- [Resources](https://docs.apivalk.com/resources/index.md): Resources are Apivalk's declarative model for CRUD endpoints. You describe a resource once and get type-safe, validated, OpenAPI-documented Create / Read / Update / Delete / List endpoints with no per-endpoint boilerplate.
- [Defining a Resource](https://docs.apivalk.com/resources/resource.md): Every CRUD surface starts with a single class extending `AbstractResource`. This page walks through each hook.
- [Resource Responses](https://docs.apivalk.com/resources/responses.md): Five response classes in `Http/Response/Resource/` mirror the five CRUD modes. They wrap `$resource->toArray($mode)` in the standard `data` envelope and emit matching OpenAPI schemas.
- [Routing](https://docs.apivalk.com/routing/index.md): Routing is the heart of the request-to-controller mapping system in Apivalk. It is designed for high performance, ease of use, and zero-configuration through automated discovery.
- [Rate Limit](https://docs.apivalk.com/routing/rate-limit.md): Rate limiting is a critical feature for protecting your API from abuse, brute-force attacks, and ensuring fair usage among all consumers.
- [Route](https://docs.apivalk.com/routing/route.md): The `Route` class is a data carrier that represents a single endpoint in your API. It encapsulates all the necessary information to map a URL and HTTP method to a specific action.
- [Router](https://docs.apivalk.com/routing/router.md): The `Router` is the primary dispatcher of the Apivalk framework. It is responsible for intercepting the incoming HTTP request and routing it to the correct controller.
- [Authenticators](https://docs.apivalk.com/security/authenticator.md): Authenticators are services responsible for turning raw credentials into an AuthIdentity.
- [Identities](https://docs.apivalk.com/security/identity.md): Identities represent the entity making the request, whether it's an authenticated user or an anonymous guest.
- [Overview](https://docs.apivalk.com/security/index.md): Apivalk features a robust, OpenAPI-compliant security and authorization system.
- [Support Policy Release Cycle](https://docs.apivalk.com/support-policy-release-cycle.md)
- [Util](https://docs.apivalk.com/util.md): The `Util` namespace in Apivalk contains helper classes and infrastructure components that provide supporting functionality for the framework's core systems, such as automated discovery and internal optimizations.

## Optional

- [Releases](https://github.com/apivalk/apivalk/releases)