Result
in package
Attributes
- #[Schema]
- $schema: 'Result'
- $title: 'Result'
- $description: 'Jednotná obálka všech API odpovědí. Užitečná data jsou v `data`.'
- $properties: [new \OpenApi\Attributes\Property(property: 'success', type: 'boolean', example: true), new \OpenApi\Attributes\Property(property: 'message', type: 'string', nullable: true, example: null), new \OpenApi\Attributes\Property(property: 'data', type: 'object', nullable: true, description: 'Payload odpovědi — tvar závisí na endpointu.'), new \OpenApi\Attributes\Property(property: 'code', type: 'integer', nullable: true, description: 'ResultCode (0 = OK; 103 = nepřihlášen; 404 = rate limit; …).', example: 0)]
Table of Contents
Constants
- ENVELOPE_KEYS : array<string|int, mixed> = ['success', 'message', 'data', 'code']
- Keys that {@see self::toArray()} always emits, in this order.
Properties
- $code : ResultCode|null
- $data : mixed
- $exception : Throwable|null
- $message : string|null
- $success : bool
Methods
- __construct() : mixed
- __invoke() : bool
- addData() : self
- Merges keys into `data` (typically what the operation produced: ids of inserted records, warnings...). The data goes into `toArray()`, so it survives the path through {@see \App\Core\Bridge\ApiBridge}.
- describeFailureEnvelope() : string
- Short description of a failed envelope for the log, e.g. `code=400 message="Permission denied"`.
- error() : self
- failure() : self
- fromArray() : self
- Rebuilds a `Result` from an array (e.g. after `json_decode`).
- getCode() : ResultCode|null
- getData() : mixed
- getException() : Throwable|null
- getMessage() : string|null
- getPublicMessage() : string
- Returns a message safe for the UI and the bridge response: for a technical {@see ResultCode::isTechnical()} code (captured exception text) it returns an empty string, so the caller shows a generic translated fallback and the detail goes only to the server log. For domain codes it returns the message unchanged.
- isFailure() : bool
- isFailureEnvelope() : bool
- Tells whether the value is a failed `Result` envelope and not data.
- isSuccess() : bool
- setData() : self
- success() : self
- toArray() : array{success: bool, message: string|null, data: mixed, code: int|null}
Constants
ENVELOPE_KEYS
Keys that {@see self::toArray()} always emits, in this order.
public
array<string|int, mixed>
ENVELOPE_KEYS
= ['success', 'message', 'data', 'code']
The envelope has no exception field: the exception text belongs only in the server
log, not in the public response.
It is the only place where the envelope shape is written as data;
self::isFailureEnvelope() and fromArray() derive from it, so extending the
envelope cannot leave the detection behind.
Properties
$code
private
ResultCode|null
$code
= null
$data
private
mixed
$data
= null
$exception
private
Throwable|null
$exception
= null
$message
private
string|null
$message
= null
$success
private
bool
$success
Methods
__construct()
public
__construct(bool $success[, string|null $message = null ][, Throwable|null $exception = null ][, mixed $data = null ][, ResultCode|null $code = null ]) : mixed
Parameters
- $success : bool
- $message : string|null = null
- $exception : Throwable|null = null
- $data : mixed = null
- $code : ResultCode|null = null
__invoke()
public
__invoke() : bool
Return values
booladdData()
Merges keys into `data` (typically what the operation produced: ids of inserted records, warnings...). The data goes into `toArray()`, so it survives the path through {@see \App\Core\Bridge\ApiBridge}.
public
addData(array<string|int, mixed> $data) : self
A null data counts as an empty array, so Result::success()->addData([...]) works.
IMPORTANT: requires an array on both sides. When the Result already carries non-array
data (an entity or a scalar, e.g. Result::success(data: $watchdogEmail)), addData()
throws instead of silently discarding it; use setData() for such a Result.
Parameters
- $data : array<string|int, mixed>
Return values
selfdescribeFailureEnvelope()
Short description of a failed envelope for the log, e.g. `code=400 message="Permission denied"`.
public
static describeFailureEnvelope(mixed $value) : string
Never prints data (it may carry personal data).
Parameters
- $value : mixed
Return values
stringerror()
public
static error([ResultCode|null $code = null ][, string|null $message = null ][, mixed $data = null ][, Throwable|null $e = null ]) : self
Parameters
- $code : ResultCode|null = null
- $message : string|null = null
- $data : mixed = null
- $e : Throwable|null = null
Return values
selffailure()
public
static failure([ResultCode|null $code = null ][, string|null $message = null ][, mixed $data = null ][, Throwable|null $e = null ]) : self
Parameters
- $code : ResultCode|null = null
- $message : string|null = null
- $data : mixed = null
- $e : Throwable|null = null
Return values
selffromArray()
Rebuilds a `Result` from an array (e.g. after `json_decode`).
public
static fromArray(array<string|int, mixed> $data) : self
Parameters
- $data : array<string|int, mixed>
Return values
selfgetCode()
public
getCode() : ResultCode|null
Return values
ResultCode|nullgetData()
public
getData() : mixed
getException()
public
getException() : Throwable|null
Return values
Throwable|nullgetMessage()
public
getMessage() : string|null
Return values
string|nullgetPublicMessage()
Returns a message safe for the UI and the bridge response: for a technical {@see ResultCode::isTechnical()} code (captured exception text) it returns an empty string, so the caller shows a generic translated fallback and the detail goes only to the server log. For domain codes it returns the message unchanged.
public
getPublicMessage() : string
Return values
stringisFailure()
public
isFailure() : bool
Return values
boolisFailureEnvelope()
Tells whether the value is a failed `Result` envelope and not data.
public
static isFailureEnvelope(mixed $value) : bool
internalAction*() returns Result::failure(PERMISSION_DENIED)->toArray() on denial. For a
caller who asked for data it is an array of four keys unrelated to the entity, and the
hydrator would process it as an entity payload (e.g. Payment::setCode() fails with a
TypeError: ?string versus int). Many entities have a public setter for an envelope
key (code, message, data), so this is a class of defects, not one entity.
Detection is strict on purpose: all four envelope keys must exist (array_key_exists,
not isset: message and data are typically null on failure) and success === false
identically. A false positive is worse than a false negative because it would discard
valid data.
Works on both transports: the external path sends sendJson(Result::failure(...)->toArray())
(RbacCheckTrait), so after Json::decode() the same
shape appears.
NOTE: a successful envelope is deliberately not detected: internalAction*() returns bare data
on success, not Result::success()->toArray(), and hydrateWithReferences() legitimately
uses the data key as an entity carrier.
Parameters
- $value : mixed
Return values
boolisSuccess()
public
isSuccess() : bool
Return values
boolsetData()
public
setData(mixed $data) : self
Parameters
- $data : mixed
Return values
selfsuccess()
public
static success([ResultCode|null $code = null ][, string|null $message = null ][, mixed $data = null ]) : self
Parameters
- $code : ResultCode|null = null
- $message : string|null = null
- $data : mixed = null
Return values
selftoArray()
public
toArray() : array{success: bool, message: string|null, data: mixed, code: int|null}