Attributes

The following page lists all available attributes which you can use at your controller.

HTTP

Param

HTTP

POST /project/12?search=foo
Content-Type: application/json
X-Version: 1.2

{
  "foo": "bar"
}

Resolves a dynamic path fragment from the path, i.e. for a path like /project/{id} you can use an argument #[Param] int $id to get the id value.

Query

HTTP

POST /project/12?search=foo
Content-Type: application/json
X-Version: 1.2

{
  "foo": "bar"
}

Resolves query parameter, i.e. you can use an argument #[Query] ?string $search to get the search value. Query arguments can be always nullable.

Header

HTTP

POST /project/12?search=foo
Content-Type: application/json
X-Version: 1.2

{
  "foo": "bar"
}

Resolves a header value, i.e. you can use an argument #[Header('X-Version')] ?string $version to get the header value. As first value of the attribute you can specify a concrete name, otherwise we try to build the name based on the argument name.

Body

HTTP

POST /project/12?search=foo
Content-Type: application/json
X-Version: 1.2

{
  "foo": "bar"
}

Resolves the body payload, i.e. you can use an argument #[Body] MyDTO $payload to parse the request payload into the DTO. Note your method must only have one #[Body] argument.

Meta

Description

Controller

final class Projects extends AbstractController
{
    #[Route('/projects/{uuid}', methods: ['GET'])]
    #[Description('Get project by UUID.')]
    #[OperationId('get-project-by-uuid')]
    public function project_by_uuid(#[Param] string $uuid): Project
    {
    }
}

Can be used at your controller method to add a general description to this operation.

OperationId

Controller

final class Projects extends AbstractController
{
    #[Route('/projects/{uuid}', methods: ['GET'])]
    #[Description('Get project by UUID.')]
    #[OperationId('get-project-by-uuid')]
    public function project_by_uuid(#[Param] string $uuid): Project
    {
    }
}

Can be used at your controller method to specify a concrete operation id, otherwise we generate the operation id based on the method and controller name.

Deprecated

Can be used to indicate that this operation is deprecated, this is then also reflected at the specification and client SDK.

Type-hints

We always recommend to generate concrete DTOs to describe the request and response payloads. If you need a raw payload we provide the following type-hints to receive a raw value.

• Psr\Http\Message\StreamInterface
  • Receive the raw request as stream application/octet-stream
• PSX\Data\Body\Json
  • Receive the raw request as JSON application/json
• PSX\Data\Body\Form
  • Receive the raw request as form application/x-www-form-urlencoded
• string
  • Receive the raw request as string text/plain

For example to write a simple proxy method which returns the provided JSON payload s.

#[Route('/post', methods: ['POST'])]
public function create(#[Body] Json $body): Json
{
    return $body;
}

Multiple response types

In case your method can return different response types you can use the #[Outgoing] attribute to define a response schema independent of the return type.

#[Route('/post', methods: ['POST'])]
#[Outgoing(201, Message::class)]
#[Outgoing(400, Error::class)]
public function create(#[Body] Post $body): JsonResponse
{
    if (empty($body->getTitle())) {
        return new JsonResponse(new Error('An error occurred'), 400);
    }

    return new JsonResponse(new Message('Post successfully created'), 201);
}