Oihana Php Controllers

ValidatorTrait uses \oihana\traits\ContainerTrait, trait:short

Provides helper methods for validation and error handling within a controller.

This trait wraps the Somnambulist validation factory: it holds the validator instance, the base and custom rule definitions, registers extra rules on the validator and turns validation failures into PSR-7 error responses.

Properties

$customRules : array<string|int, mixed>: The custom validation rules definitions.
$rules : array<string|int, mixed>: The rules definitions used in the prepareRules method to initialize a validation process in the POST/PATCH/PUT and custom methods.
$validator : Factory: The validator reference.

Methods

addRules() : void: Registers extra rules on the internal validator.
fail() : ResponseInterface|null: Generates a structured error response with an HTTP status code and optional detailed messages.
getValidatorError() : ResponseInterface|null: Returns an error if the validator fails.
initCustomValidationRules() : array<string|int, mixed>: Returns the list of all extra-rules to initialize the validator.
initializeValidator() : static: Sets the current internal validator of the controller.
prepareRules() : array<string|int, mixed>: Merge the default common and the specific method's rules.
response() : ResponseInterface: Return a response in the format accepted by the client : JSON by default or CBOR.
status() : ResponseInterface|null: Outputs a generic HTTP status message in a JSON response.
success() : mixed: Outputs a success message with optional JSON metadata.
successWithNewBody() : mixed: Same as {@see self::success()} but guarantees a fresh response body stream before writing the envelope.
withFreshBody() : ResponseInterface|null: Returns the same response with a fresh, empty body stream.

$customRules

The custom validation rules definitions.


        public
            array<string|int, mixed>
    $customRules
     = []

$rules

The rules definitions used in the prepareRules method to initialize a validation process in the POST/PATCH/PUT and custom methods.


        public
            array<string|int, mixed>
    $rules
     = []

$validator

The validator reference.


        public
            Factory
    $validator

addRules()

Registers extra rules on the internal validator.


    public
                    addRules([array<string|int, mixed> $rules = [] ]) : void

Each entry maps a rule name to a Rule instance. A string value is resolved from the DI container when it references a known entry before being registered.

Parameters

$rules : array<string|int, mixed> = []: An associative array of ruleName => Rule|string definitions to register.

fail()

Generates a structured error response with an HTTP status code and optional detailed messages.


    public
                    fail(ServerRequestInterface|null $request, ResponseInterface|null $response[, int|string|null $code = 400 ][, string|null $details = null ][, array<string|int, mixed> $options = [] ][, string|null $accept = null ]) : ResponseInterface|null

Automatically logs the error if logging is enabled.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: The PSR-7 Response object.
$code : int|string|null = 400: The HTTP status code (default: 400).
$details : string|null = null: Optional detailed error message to override default description.
$options : array<string|int, mixed> = []: Optional array of additional data to include (e.g., errors).
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->fail(
    $response,
    406,
    'fields validation failed',
    [
        'firstName' => 'firstName is required',
        'lastName'  => 'lastName must be a string'
    ]
);

Return values

ResponseInterface|null —

Returns a PSR-7 Response object with JSON content or null if $response is not provided.

getValidatorError()

Returns an error if the validator fails.


    public
                    getValidatorError(ServerRequestInterface|null $request, ResponseInterface|null $response, Validation $validation[, array<string|int, mixed> $errors = [] ][, int|string $code = 400 ]) : ResponseInterface|null

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: The PSR-7 Response object.
$validation : Validation: The validation result to inspect for failures.
$errors : array<string|int, mixed> = []: Optional initial errors merged with the validation errors.
$code : int|string = 400: The HTTP status code of the error response (defaults to 400).

Return values

ResponseInterface|null —

The failure response, or null when no response object was provided.

initCustomValidationRules()

Returns the list of all extra-rules to initialize the validator.


    public
                    initCustomValidationRules() : array<string|int, mixed>

Overrides this method to extends the default rules definitions.

Return values

array<string|int, mixed> —

The custom validation rules to register on the validator.

initializeValidator()

Sets the current internal validator of the controller.


    public
                    initializeValidator([array<string|int, mixed> $init = [] ]) : static

By default, creates a new Validator instance and initialize it.

Parameters

$init : array<string|int, mixed> = []: Initialization array, read from the ControllerParam::VALIDATOR, ControllerParam::CUSTOM_RULES and ControllerParam::RULES keys.

Return values

static —

Returns the current instance for method chaining.

prepareRules()

Merge the default common and the specific method's rules.


    public
                    prepareRules([string|null $method = null ]) : array<string|int, mixed>

You can overrides this method to prepare the validator rules with a specific router method and strategy.

Parameters

$method : string|null = null: The specific rule type to override the default rules definitions.

Return values

array<string|int, mixed> —

The merged rules, combining the HttpMethod::ALL rules with the method-specific ones.

response()

Return a response in the format accepted by the client : JSON by default or CBOR.


    public
                    response(ResponseInterface $response[, mixed $data = null ][, int $status = 200 ][, string|null $accept = null ]) : ResponseInterface

Checks the Accept header in the request to determine the preferred format.

Parameters

$response : ResponseInterface: PSR-7 Response object to write to.
$data : mixed = null: Data to send in the response.
$status : int = 200: HTTP status code (default: 200).
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Return values

ResponseInterface —

The response encoded as CBOR or JSON according to the negotiated format.

status()

Outputs a generic HTTP status message in a JSON response.


    public
                    status(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $message = Char::EMPTY ][, int|string|null $code = 200 ][, array<string|int, mixed>|null $options = null ][, string|null $accept = null ]) : ResponseInterface|null

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: PSR-7 Response object to send output.
$message : mixed = Char::EMPTY: The message content.
$code : int|string|null = 200: The HTTP status code (default: 200).
$options : array<string|int, mixed>|null = null: Optional array of additional output properties.
$accept : string|null = null: The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->status($response, 'bad request', 405);

Return values

ResponseInterface|null —

Returns a PSR-7 Response object with JSON content or null if $response is not provided.

success()

Outputs a success message with optional JSON metadata.


    public
                    success(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $data = null ][, array<string|int, mixed>|null $init = null ][, string|null $accept = null ]) : mixed

If $response is null, returns the $data directly. Supports optional initialization properties like count, limit, offset, owner, URL, status, total, position, options.

Parameters

$request : ServerRequestInterface|null

Optional PSR-7 Request object.

$response : ResponseInterface|null

Optional PSR-7 Response object.

$data : mixed = null

The main payload or data to return.

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

Optional associative array with keys:

count (int): Number of elements
limit (int): Pagination limit
offset (int): Pagination offset
params (array): Parameters for getCurrentPath()
status (int): HTTP status code
total (int): Total elements
url (string): URL to include in response
owner (array|object): Owner reference
options (array): Additional properties
position (int): Optional position in list

$accept : string|null = null

The header accepted by the client : 'application/cbor' or by default 'application/json'

Tags

example

return $this->success(
    $request,
    $response,
    $data,
    [Output::COUNT => count($data), Output::PARAMS => $request->getQueryParams()]
);

Return values

mixed —

Returns a PSR-7 Response object with JSON if $response is provided, otherwise returns $data directly.

successWithNewBody()

Same as {@see self::success()} but guarantees a fresh response body stream before writing the envelope.


    public
                    successWithNewBody(ServerRequestInterface|null $request, ResponseInterface|null $response[, mixed $data = null ][, array<string|int, mixed>|null $init = null ][, string|null $accept = null ]) : mixed

Use this only when an upstream actor (typically a sub-controller called from the current controller method) may have already written into the shared PSR-7 body stream. Calling the plain success() in that case would concatenate two JSON envelopes — invalid JSON for any strict parser (NextJS RSC, modern fetch, etc.).

Implementation: swaps the response body for an empty stream via self::withFreshBody(), then delegates to success(). Whatever was previously written is discarded; the resulting body contains exactly one envelope.

Parameters

$request : ServerRequestInterface|null: Optional PSR-7 Request object.
$response : ResponseInterface|null: Optional PSR-7 Response object.
$data : mixed = null: The main payload or data to return.
$init : array<string|int, mixed>|null = null: Same keys as success().
$accept : string|null = null: The header accepted by the client.

Tags

example

// POST /users where dispatchAutoInvitation() writes into the shared body
public function post( ?Request $request , ?Response $response , array $args , array $init ) :mixed
{
    $result = parent::post( $request , $response , $args , $init ) ;
    $this->dispatchAutoInvitation( $request , $response , $userKey ) ;

    return $this->successWithNewBody
    (
        $request ,
        $result  ,
        $this->refetchHydratedUser( $userKey )
    ) ;
}

see

success()

Plain variant when the body has not been touched.

Return values

mixed —

Same return contract as success().

withFreshBody()

Returns the same response with a fresh, empty body stream.


    public
                    withFreshBody(ResponseInterface|null $response) : ResponseInterface|null

Use to discard whatever an upstream actor (sub-controller, middleware) may have already written, then chain into any other response helper.

Parameters

$response : ResponseInterface|null: Optional PSR-7 Response object.

Tags

example

return $this->fail( $request , $this->withFreshBody( $response ) , 502 , 'zitadel_sync_failed' ) ;

Return values

ResponseInterface|null —

The same response with a fresh empty body, or null if $response was null.

ValidatorTrait uses \oihana\traits\ContainerTrait, trait:short

Tags

Table of Contents

Properties

Methods

Properties

$customRules

$rules

Tags

$validator

Methods

addRules()

Parameters

Tags

fail()

Parameters

Tags

Return values

getValidatorError()

Parameters

Return values

initCustomValidationRules()

Return values

initializeValidator()

Parameters

Tags

Return values

prepareRules()

Parameters

Return values

response()

Parameters

Tags

Return values

status()

Parameters

Tags

Return values

success()

Parameters

Tags

Return values

successWithNewBody()

Parameters

Tags

Return values

withFreshBody()

Parameters

Tags

Return values