phpEZ v0.4.1

Api
in package

Represents a single API endpoint with smart request handling.

The Api class encapsulates routing logic and automatic parameter injection. It intelligently maps request data to handler parameters based on their type hints:

  • int / string: Extracted from URL path pattern matches (e.g., {id:i}, {slug:s})
  • Obj subclasses: Deserialized from request body (JSON)
  • BoolGet / Get: Automatically instantiated for GET parameter access
  • DOMDocument: Parsed from raw XML request body
  • string (body): Raw request body as string
  • array (body): JSON decoded request body as array

Response types are automatically serialized:

  • null / array: Returned as JSON data
  • Objects with __serialize(): Method is called for serialization
  • HTTPCode enum: HTTP status code is set, no body is sent

Path pattern syntax:

  • {id:i} - Named integer parameter
  • {slug:s} - Named string parameter (word characters)
  • /static/path - Literal path segment

Example:

$api = new Api(
  HTTP::POST,
  '/users/{id:i}/posts',
  function(int $id, CreatePostRequest $body) {
    return new PostResponse(...);
  }
);
Tags
subpackage

http

Table of Contents

Properties

$handler  : Closure
$method  : HTTP
$path  : string
$regx  : bool

Methods

__construct()  : mixed
Create a new API endpoint handler.
match()  : bool
Test if a request path matches this endpoint's path pattern.
run()  : never
Execute the handler with automatic parameter injection.

Properties

$handler read-only

public Closure $handler

$path read-only

public string $path

$regx read-only

public bool $regx = false

Methods

__construct()

Create a new API endpoint handler.

public __construct(HTTP $method, string $path, Closure $handler[, bool $regx = false ]) : mixed
Parameters
$method : HTTP

The HTTP method this endpoint responds to.

$path : string

The URL path pattern (may include {name:type} parameters).

$handler : Closure

The callback to execute. Return value is automatically serialized. Parameters are auto-injected based on type hints.

$regx : bool = false

Unused flag for future regex support. Default false.

match()

Test if a request path matches this endpoint's path pattern.

public match(string $path[, array<string|int, mixed>|null &$matches = null ]) : bool

Converts path patterns with parameters to regex and tests against the given path. Extracts named parameters into the $matches array for handler injection.

Pattern conversion:

  • {name:i} → (?<name>\d+) (integer)
  • {name:s} → (?<name>\w+) (word characters)
  • Literal segments are escaped for regex
Parameters
$path : string

The incoming request path to test.

$matches : array<string|int, mixed>|null = null

Output array that will contain named parameter matches. Only populated if the path matches.

Return values
bool —

True if the path matches this endpoint's pattern.

run()

Execute the handler with automatic parameter injection.

public run(array<string|int, mixed>|null $matchArgs) : never

Uses reflection to inspect handler parameters and automatically injects:

  • URL path parameters (matched by name and converted by type)
  • Request body (JSON, XML, or raw)
  • Query parameters (Get/BoolGet instances)

Serializes the response based on its type and sends it via final_json().

Parameters
$matchArgs : array<string|int, mixed>|null

Extracted URL parameters from path pattern matching. Keys are parameter names, values are strings from URL.

Tags
throws
HTTPException

For missing type hints, unsupported parameter types, or unsupported output types.

Return values
never —

This function always terminates execution via final_json().

On this page

Search results