---

Annotated

The annotated router class.

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>', methodsGET'])
  * @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.

• Full name: \Hazaar\Application\Router\Loader\Annotated
• Parent class: \Hazaar\Application\Router\Loader\Advanced

Properties

validTypes

protected static string[] $validTypes

• This property is static.

---

controllerEndpoints

private array<string,array> $controllerEndpoints

---

describeFull

private bool $describeFull

---

Methods

describeAPI

Private method to describe the REST API.

public describeAPI(): array

Return Value:

returns an array containing the description of the REST API

---

exec

public exec(\Hazaar\Application\Request $request): bool

Parameters:

Parameter	Type	Description
$request	\Hazaar\Application\Request

---

getEndpointTags

Get the tags for a given endpoint name.

protected getEndpointTags(string $name): string[]|false

Parameters:

Parameter	Type	Description
$name	string	the name of the endpoint

Return Value:

the tags for the endpoint or false if not found

---

loadEndpoints

private loadEndpoints(string $controllerClass): array

Parameters:

Parameter	Type	Description
$controllerClass	string

---

describeEndpoint

Describes an endpoint by generating an array of information about the endpoint.

private describeEndpoint(array $endpoint, bool $describe_full = false, array& $api = null): array

Parameters:

Parameter	Type	Description
$endpoint	array	the endpoint to describe
$describe_full	bool	whether to include full description or not
$api	array	the array to append the endpoint information to

Return Value:

the array of information about the endpoint

---

Inherited methods

__construct

public __construct(\Hazaar\Map $config): mixed

Parameters:

Parameter	Type	Description
$config	\Hazaar\Map

---

exec

public exec(\Hazaar\Application\Request $request): bool

Parameters:

Parameter	Type	Description
$request	\Hazaar\Application\Request

---

evaluateAliases

Evaluates the request and sets the controller, action, and arguments based on the request path.

private evaluateAliases(string $route, array<string,string> $aliases): string

Parameters:

Parameter	Type	Description
$route	string	the request path
$aliases	array<string,string>	the aliases

Return Value:

the evaluated path

---

findController

Finds the controller based on the given parts.

private findController(string $path, string[]& $controllerParts): string

Parameters:

Parameter	Type	Description
$path	string	the name of the controller
$controllerParts	string[]

Return Value:

the name of the controller

---

---

Automatically generated on 2024-11-14