Annotated

Annotation/doc-comment driven route loader.

class Annotated extends \Hazaar\Application\Router\Loader\Advanced

This controller can be used to create RESTful API endpoints. It automatically handles HTTP request methods and can send appropriate responses for invalid requests. It can also provide an intelligent API endpoint directory.

Overview

Unlike other controllers, the rest controller works using annotations. Such as:

class ApiController extends \Hazaar\Controller\REST {
  /**
   * @route('/dothething/<int:thingstodo>', methods=['GET'])
   **\/
  protected function do_the_thing($thingstodo){
    return ['things' => 'Array of things'];
  }
}

This endpoint will be accessible at the URL: http://yourhost.com/api/v1/dothething/1234

Versions

It is possible to add your own "version control" to the REST api by defining multiple functions for the same route. Using versions allows you to easily update your API without removing backwards compatibility. New versions should be used when there is a major change to either the input or output of your endpoint and renaming it is not reasonable.

Do define another version of the above example using versions you could:

class ApiController extends \Hazaar\Controller\Basic {
   * @route('/v1/dothething/{int:thingstodo}', methods={"GET"})
   **\/
  protected function do_the_thing($thingstodo){
    return ['things' => 'Array of things'];
  }
   * @route('/v2/dothething/{date:when}/{int:thingstodo}', methods={"GET"})
   **\/
  protected function do_the_thing_v2($thingstodo, $when){
    if($when->year() >= 2023){
      return ['things' => 'Array of FUTURE things'];
    }

    return ['things' => 'Array of things'];
  }
}

This endpoint will be accessible at the URL: http://yourhost.com/api/v1/dothething/2040-01-01/1234

Endpoints on multiple versions

To allow an endpoint to be available on multiple versions of your API, simply add multple @routes

Such as:

  * @route('/v1/dothething/{date:when}/{int:thingstodo}', methods={"GET"})
  * @route('/v2/dothething/{date:when}/{int:thingstodo}', methods={"GET"})
  **\/

Endpoint Directories

Endpoint directories are simply a list of the available endpoints with some basic information about how they operate such as the HTTP methods allowed, parameter description and a brief description.

Properties

validTypes

protected array $validTypes = array (
  0 => 'boolean',
  1 => 'bool',
  2 => 'integer',
  3 => 'int',
  4 => 'double',
  5 => 'float',
  6 => 'string',
  7 => 'array',
  8 => 'null',
  9 => 'date',
)

Methods

evaluateRequest

Evaluates the request and expands controller annotations into concrete routes.

public evaluateRequest(Request $request): ?Route

This method first delegates controller resolution to the parent loader. If a controller route is found, it loads annotated endpoints for that controller and registers them on the active router using the discovered route metadata.

Parameters

Parameter	Type	Description
$request	Request	incoming application request

loadEndpoints

private loadEndpoints(string $controllerClass): void

Parameters

Parameter	Type	Description
$controllerClass	string

decodeParameterValue

Decodes annotation argument values into native PHP types.

private decodeParameterValue(string $key, string $value): mixed

Supports scalar values, booleans, numeric values, indexed arrays ([...]), associative maps ({key=value,...}), and date-like keys (date, datetime). Decoding is recursive for nested array/map structures.

Parameters

Parameter	Type	Description
$key	string	annotation argument name
$value	string	raw argument value extracted from the annotation parser

---

Generated by Hazaar API Doc Generator on Tue, 21 Apr 2026 04:00:25 +0000