JSON:API Controller

JsonApiController provides generic CRUD operations following the JSON:API specification: request/response formatting, resource validation, and a per-attribute write-authorization gate. Extend it when an entity needs a CRUD API and you want explicit control over which fields a client can set, independent of the entity's own getters and setters.

Basic Usage

Extend JsonApiController, implement getEntityClass() and getResourceType(), and route your own methods to the inherited getResource(), createResource(), updateResource(), and deleteResource() helpers:

<?php
namespace App\Controllers;

use App\Entities\ProductEntity;
use Quellabs\Canvas\Controllers\JsonApiController;
use Quellabs\Canvas\Annotations\Route;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

class ProductController extends JsonApiController {

    protected function getEntityClass(): string {
        return ProductEntity::class;
    }

    protected function getResourceType(): string {
        return 'products';
    }

    /**
     * @Route("/api/products/{id}", methods={"GET"})
     */
    public function show(int $id): JsonResponse {
        return $this->getResource($id);
    }

    /**
     * @Route("/api/products", methods={"POST"})
     */
    public function store(Request $request): JsonResponse {
        return $this->createResource($request);
    }

    /**
     * @Route("/api/products/{id}", methods={"PUT", "PATCH"})
     */
    public function update(int $id, Request $request): JsonResponse {
        return $this->updateResource($id, $request);
    }

    /**
     * @Route("/api/products/{id}", methods={"DELETE"})
     */
    public function destroy(int $id): JsonResponse {
        return $this->deleteResource($id);
    }
}

The four helpers are protected on purpose — your controller decides the routes and HTTP methods that call them, nothing is auto-routed.

Write Authorization

Every attribute submitted to createResource() or updateResource() passes through validation before anything is written to the entity. Validation matches the submitted keys against the entity's declared properties only — a setter does not define an attribute beyond what the entity declares:

• A key that doesn't case-insensitively match any declared property is unknown — the whole request is rejected with 422 (typo, stale client field).
• A key that matches a declared property only with different casing is forbidden with 403, never silently coerced to the canonical casing — there's no reliable way to recover the "correct" casing from an acronym setter (setID() could back property id or iD).
• The entity's primary key is always forbidden with 403, regardless of isAttributeWritable() — a client can never reassign which row a request writes to.
• Every other declared property is decided by isAttributeWritable(), which defaults to allowing everything.

Override isAttributeWritable() to deny specific fields, operations, or circumstances:

use Quellabs\Canvas\Controllers\WriteOperation;

protected function isAttributeWritable(object $entity, string $key, WriteOperation $operation): bool {
    // Keep role server-owned
    if ($key === 'role') {
        return false;
    }

    // Allow setting the slug only when creating, never on update
    if ($key === 'slug') {
        return $operation === WriteOperation::Create;
    }

    return true;
}

Whether an attribute has a setter or not plays no role in this decision — it only affects how mapAttributesToEntity() writes the value afterwards: through the setter when one exists, directly via reflection otherwise.

Resource-Level Authorization

For checks a per-attribute decision can't express — ownership, role, or current entity state — override authorizeAttributeWrite(). It runs before any attribute is validated or mapped, so it can deny a write purely based on the resource, regardless of which fields were submitted:

use Quellabs\Canvas\Controllers\WriteOperation;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

protected function authorizeAttributeWrite(Request $request, object $entity, WriteOperation $operation): ?JsonResponse {
    if ($operation === WriteOperation::Update && $entity->getOwnerId() !== $this->currentUserId()) {
        return $this->forbidden('You do not own this resource');
    }

    return null;
}

Error Responses

Errors follow the JSON:API error object format, with a source.pointer identifying the offending attribute where applicable:

Generating Controllers from Entities

Running php vendor/bin/sculpt make:pac-entity EntityName (provided by ObjectQuel) scaffolds a JsonApiController subclass alongside the WakaPAC JavaScript abstraction. The generated isAttributeWritable() stub returns true — matching the allow-by-default base — and lists the entity's non-identifier properties in a comment purely as a starting point for review; no field is denied automatically.