REST Serialization

REST API v2 response shaping

Every Endpoint handler returns an EndpointResult — a (modelClass, data, meta) triple. The framework's normalizer instantiates the Model with the data, calls toArray(), wraps it in {data: ..., meta: {...}, rels: {...}}, and returns JSON. The Model class is where you decide which entity fields appear in the response and what JSON keys they go under.

Endpoint handler
  └── returns new EndpointResourceResult(WidgetModel::class, $widgetEntity, ?$meta)
       └── framework: $model = new WidgetModel($widgetEntity)
            └── $model->toArray()                  ← ModelTrait does the heavy lifting
                 └── walks `filter` array, builds `attributeNames`-keyed output
       └── Response::formatData()
            └── {"data": {...model output...}, "meta": {...}, "rels": {...}}

This skill covers everything from "what to return from the handler" through "how the JSON envelope is built." For the dispatch flow into the handler, see rest-endpoints. For the @OA\Schema annotation that documents the Model, see rest-openapi.

The Normalizable contract

A Model is any class implementing OrangeHRM\Core\Api\V2\Serializer\Normalizable:

interface Normalizable
{
    public function toArray(): array;
}

You almost never implement this directly. The standard pattern is to use ModelTrait and wire an entity in the constructor.

ModelTrait — the standard pattern

ModelTrait gives a Normalizable class three setters and an implementation of toArray():

$this->setEntity($entity);             // the Doctrine entity (or any object with getters)
$this->setFilters([...]);              // which fields to include, as a getter chain
$this->setAttributeNames([...]);       // the JSON output key for each filter entry

toArray() walks the filter array; for each entry, it derives a getter (string → get<UcfirstAttr>()), invokes it on the entity, and stores the result under the matching attributeNames[$index] key (or under filter[$index] itself if no override).

The basic shape

namespace OrangeHRM\X\Api\Model;

use OrangeHRM\Core\Api\V2\Serializer\ModelTrait;
use OrangeHRM\Core\Api\V2\Serializer\Normalizable;
use OrangeHRM\Entity\Widget;

class WidgetModel implements Normalizable
{
    use ModelTrait;

    public function __construct(Widget $widget)
    {
        $this->setEntity($widget);
        $this->setFilters(['id', 'name', 'description']);
        // Attribute names default to filter strings when omitted — these would be {id, name, description}
    }
}

The framework calls getId(), getName(), getDescription() on the entity (camel-cased + get prefix). Output:

{ "id": 1, "name": "Acme", "description": "…" }

Renaming output keys

If JSON key shouldn't match the getter name (e.g. you want lastName in JSON but the getter is getLast()), provide attributeNames:

$this->setFilters(['id', 'last', 'first', 'middle']);
$this->setAttributeNames(['id', 'lastName', 'firstName', 'middleName']);

The two arrays are positional — index 0 of attributeNames matches index 0 of filter. Mismatch in length silently produces shifted output, so keep them aligned.

Nested getters — descending into related entities

When the value you want lives on a related entity, pass a sub-array of getter names instead of a string. ModelTrait walks the chain, calling each method on the previous result.

$this->setFilters([
    'empNumber',
    'lastName',
    'firstName',
    'middleName',
    'employeeId',
    ['getEmployeeTerminationRecord', 'getId'],  // $employee->getEmployeeTerminationRecord()->getId()
]);
$this->setAttributeNames([
    'empNumber',
    'lastName',
    'firstName',
    'middleName',
    'employeeId',
    'terminationId',                            // the JSON key for the nested chain
]);

Output:

{
  "empNumber": 1,
  "lastName": "…",
  ...,
  "terminationId": 42                          // null if no termination record
}

Null-safety is automatic at each link. ModelTrait::toArray() checks is_null($value) before each step — if getEmployeeTerminationRecord() returns null, the chain short-circuits and the output value is null (without calling getId() on null). This is convenient but masks errors: if you typo a getter name, the chain silently produces null instead of throwing.

Producing nested JSON objects

If you want a nested JSON object instead of a flat key, provide a sub-array under attributeNames for that index:

$this->setFilters([
    'id',
    ['getJobTitle', 'getId'],
    ['getJobTitle', 'getJobTitleName'],
]);
$this->setAttributeNames([
    'id',
    ['jobTitle', 'id'],          // nested: { "jobTitle": { "id": … } }
    ['jobTitle', 'name'],        // merged: { "jobTitle": { "id": …, "name": … } }
]);

ModelTrait::makeNestedArray() builds the nested structure; array_merge_recursive combines the two entries into one jobTitle object. Use this when the response should surface a sub-resource rather than flat scalars.

Collections within a model

If a step in the getter chain returns an iterable (e.g. getSkills() returns Collection<EmployeeSkill>), the trait switches to collection mode: the remaining getter names are applied to each element, and the result is an array under the model's output key.

$this->setFilters([
    'id',
    ['getSkills', ['getName', 'getYears']],
]);
$this->setAttributeNames([
    'id',
    ['skills', ['name', 'years']],
]);

Output:

{ "id": 1, "skills": [{"name": "PHP", "years": 5}, {"name": "Vue", "years": 3}] }

The trait detects the iterable at any point in the chain and switches mode automatically.

Picking the result class

EndpointResourceResult is also used for delete responses (which echo back the deleted IDs) and MyInfo-style endpoints. The interface is the same shape; the result type is the only difference between one-vs-many output.

// Single
return new EndpointResourceResult(WidgetModel::class, $widget);

// Collection with meta total
return new EndpointCollectionResult(
    WidgetModel::class,
    $widgets,
    new ParameterBag([CommonParams::PARAMETER_TOTAL => $count])
);

The constructor signature is (string $modelClass, $data, ?ParameterBag $meta = null, ?ParameterBag $rels = null). $rels is rarely used in this codebase — it would surface as a rels key in the envelope.

ParameterBag for meta

OrangeHRM\Core\Api\V2\ParameterBag (extends Symfony's ParameterBag) holds the response's meta object. The framework always emits a meta key — pass an empty ParameterBag or null for { "meta": {} }.

The single project-wide convention: list endpoints include total:

new ParameterBag([CommonParams::PARAMETER_TOTAL => $count])
// → {"meta": {"total": 137}}

Some endpoints add more keys (e.g. employee-list reports add employeeIds or filter-summary data). Always use CommonParams::PARAMETER_* constants when the key is a framework-standard one.

The response envelope

Response::formatData() always produces:

{
  "data": { ... model output ... },     // or [...] for collection
  "meta": { ... },
  "rels": { ... }
}

meta and rels default to {} when not set. Errors are a separate shape produced by Response::formatError() — { "error": { "status": "...", "message": "..." } }.

Generic models (non-entity payloads)

When your response isn't backed by a Doctrine entity, use the generic models instead of inventing an entity:

ArrayModel($data)

Single response. Pass an associative array; that array becomes the data key verbatim.

return new EndpointResourceResult(ArrayModel::class, ['valid' => true]);
// → {"data": {"valid": true}, "meta": {}, ...}

Common uses: validation-only endpoints ({valid: true}), delete responses (echoing back the IDs), single-field reads.

ArrayCollectionModel($data)

Collection. Pass a plain array; becomes data as a JSON array.

return new EndpointCollectionResult(ArrayCollectionModel::class, [1, 2, 3]);
// → {"data": [1, 2, 3], "meta": {}, ...}

Used when "the list" doesn't map to entities — version constants, computed aggregates, etc.

The MODEL_MAP pattern — ?model=default|detailed

For endpoints where consumers want either a slim or a rich version of the same resource, declare a MODEL_MAP constant and switch on a ?model= query param. EmployeeAPI is the canonical example:

class EmployeeAPI extends Endpoint implements CrudEndpoint
{
    public const FILTER_MODEL = 'model';
    public const MODEL_DEFAULT  = 'default';
    public const MODEL_DETAILED = 'detailed';
    public const MODEL_MAP = [
        self::MODEL_DEFAULT  => EmployeeModel::class,
        self::MODEL_DETAILED => EmployeeDetailedModel::class,
    ];

    protected function getModelClass(): string
    {
        $model = $this->getRequestParams()->getString(
            RequestParams::PARAM_TYPE_QUERY,
            self::FILTER_MODEL,
            self::MODEL_DEFAULT,
        );
        return self::MODEL_MAP[$model];
    }

    protected function getModelParamRule(): ParamRule
    {
        return $this->getValidationDecorator()->notRequiredParamRule(
            new ParamRule(self::FILTER_MODEL,
                new Rule(Rules::IN, [array_keys(self::MODEL_MAP)])
            )
        );
    }

    public function getOne(): EndpointResourceResult
    {
        // ...
        return new EndpointResourceResult($this->getModelClass(), $employee);
    }

    public function getValidationRuleForGetOne(): ParamRuleCollection
    {
        return new ParamRuleCollection(
            new ParamRule(CommonParams::PARAMETER_EMP_NUMBER, new Rule(Rules::IN_ACCESSIBLE_EMP_NUMBERS)),
            $this->getModelParamRule(),
        );
    }
}

The EmployeeDetailedModel adds nested chains for job title, employment status, supervisor, etc. — same entity, expanded filter and attributeNames arrays. The handler doesn't know or care which one was picked.

Use this pattern when:

• The "rich" version triggers extra DB joins you don't want by default
• Different consumers (mobile app vs. admin UI) want different field sets
• You'd otherwise be tempted to add ?include=jobTitle,supervisor style toggles

Avoid when:

• The difference is one or two fields — just include them by default
• Variants would proliferate (detailed, verbose, minimal, internal) — at that point, design a field-selection mechanism instead

Recipes

Recipe 1 — A basic Model for a Doctrine entity

namespace OrangeHRM\X\Api\Model;

use OrangeHRM\Core\Api\V2\Serializer\ModelTrait;
use OrangeHRM\Core\Api\V2\Serializer\Normalizable;
use OrangeHRM\Entity\Widget;

class WidgetModel implements Normalizable
{
    use ModelTrait;

    public function __construct(Widget $widget)
    {
        $this->setEntity($widget);
        $this->setFilters([
            'id',
            'name',
            'description',
            ['getOwner', 'getEmpNumber'],
            ['getOwner', 'getLastName'],
        ]);
        $this->setAttributeNames([
            'id',
            'name',
            'description',
            ['owner', 'empNumber'],          // nested {owner: {empNumber, lastName}}
            ['owner', 'lastName'],
        ]);
    }
}

Output:

{ "id": 1, "name": "Acme", "description": "…",
  "owner": { "empNumber": 7, "lastName": "Smith" } }

Recipe 2 — Default vs detailed variants

Already shown above (the MODEL_MAP pattern). The detailed model has the same constructor signature but bigger filter/attributeNames arrays:

class WidgetDetailedModel implements Normalizable
{
    use ModelTrait;

    public function __construct(Widget $widget)
    {
        $this->setEntity($widget);
        $this->setFilters([
            'id', 'name', 'description', 'createdAt', 'updatedAt',
            ['getOwner', 'getEmpNumber'],
            ['getOwner', 'getLastName'],
            ['getOwner', 'getFirstName'],
            ['getCategory', 'getId'],
            ['getCategory', 'getName'],
            ['getTags', ['getId', 'getName']],     // collection inside the model
        ]);
        $this->setAttributeNames([
            'id', 'name', 'description', 'createdAt', 'updatedAt',
            ['owner', 'empNumber'],
            ['owner', 'lastName'],
            ['owner', 'firstName'],
            ['category', 'id'],
            ['category', 'name'],
            ['tags', ['id', 'name']],
        ]);
    }
}

Recipe 3 — Validation-only / single-field response (no entity)

public function getOne(): EndpointResourceResult
{
    $isUnique = $this->getService()->isUniqueEmail($email);
    return new EndpointResourceResult(ArrayModel::class, ['valid' => $isUnique]);
}

Recipe 4 — Delete-response echo

The delete handler echoes the deleted IDs back to the client. Use ArrayModel:

public function delete(): EndpointResourceResult
{
    $ids = $this->getRequestParams()->getArray(
        RequestParams::PARAM_TYPE_BODY, CommonParams::PARAMETER_IDS
    );
    $this->getWidgetService()->deleteWidgets($ids);
    return new EndpointResourceResult(ArrayModel::class, $ids);
}

This is the convention across the codebase. Look at any plugin's delete() to confirm — they all return ArrayModel with the IDs.

Recipe 5 — Collection with total + extra meta

return new EndpointCollectionResult(
    EmployeeModel::class,
    $employees,
    new ParameterBag([
        CommonParams::PARAMETER_TOTAL => $count,
        'filterSummary' => ['activeCount' => $activeCount, 'terminatedCount' => $terminatedCount],
    ])
);

Output:

{
  "data": [{...}, {...}],
  "meta": { "total": 137, "filterSummary": { "activeCount": 120, "terminatedCount": 17 } },
  "rels": {}
}

Checklists

Writing a new Model class

• File location: src/plugins/orangehrm{X}Plugin/Api/Model/<Name>Model.php
• implements Normalizable; use ModelTrait;
• Constructor takes the entity (typed); calls setEntity, setFilters, setAttributeNames
• filter and attributeNames arrays are the same length and aligned by index
• Nested chains ([getX, getY]) for related entities; output key is the matching attributeNames entry
• For nested output objects, use ['outerKey', 'innerKey'] in attributeNames
• Add an @OA\Schema block — see the rest-openapi skill
• If detailed variant needed: register a MODEL_MAP in the Endpoint and switch on ?model=

Picking the result class

• Single resource → EndpointResourceResult
• Collection → EndpointCollectionResult
• Non-entity object payload → ArrayModel + EndpointResourceResult
• Non-entity array payload → ArrayCollectionModel + EndpointCollectionResult
• Delete echo → ArrayModel + EndpointResourceResult
• Include total in meta for list endpoints — convention: new ParameterBag([CommonParams::PARAMETER_TOTAL => $count])

Debug "field missing / null in JSON"

• Field absent from response → not in filter array
• Field appears under wrong JSON key → filter and attributeNames indices misaligned
• Nested field shows up as null → an intermediate getter returned null; ModelTrait short-circuits the chain silently. Verify by calling the getter manually
• Nested field shows up as null but the related entity exists → typo in the getter name in the filter chain; the silent null-safety hides this
• Detailed model returns default fields → handler is using EmployeeModel::class instead of $this->getModelClass()
• Collection items have inconsistent shape → the entity for some items has lazy-loaded relations not yet materialized; force-fetch in the service before normalization

Things that bite

• ModelTrait chain null-safety is silent. A typo in a nested getter (getEmployeeTerminationRecord vs getEmpTerminationRecord) produces null, not an error. Verify chains against the entity class's real getter list when adding nested fields.
• filter and attributeNames are positional, not associative. Off-by-one in one but not the other shifts every key from that point on.
• EndpointResourceResult vs EndpointCollectionResult use the same constructor signature but produce data: {...} vs data: [...]. Picking the wrong one produces JSON that won't parse the way the client expects.
• Generic models (ArrayModel, ArrayCollectionModel) bypass entity getters. Whatever you pass becomes the data verbatim — null-safety, type coercion, and attributeNames mapping do not apply.
• MODEL_MAP ?model= validation must use Rules::IN, not a custom rule — ?model=garbage should be a 422, not a 500 from MODEL_MAP[$invalid].
• Meta is a ParameterBag, not an array — pass new ParameterBag([...]), not the array directly. Construct errors here become "Argument must be of type ParameterBag, array given" at runtime.