project-manager/src/Http/Controllers/CardController.php

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Exception\ApiException;
use App\Repository\CardRepository;
use App\Repository\CardStatusRepository;
use App\Repository\ProjectRepository;
use App\Support\Validator;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;

/**
 * CRUD for cards. A card either sits in the caller's inbox (no project) or
 * belongs to one of their projects with a status in it; single-card and
 * ordering routes are addressed globally (by card id, or by an explicit
 * project_id/status_id column) since a card need not have a project.
 */
final class CardController extends Controller
{
    private const TEXT_MAX = 1000;

    public function __construct(
        private readonly ProjectRepository $projects,
        private readonly CardRepository $cards,
        private readonly CardStatusRepository $statuses,
    ) {
    }

    /**
     * GET /api/projects/{projectId}/cards
     */
    public function index(Request $request, Response $response, array $args): Response
    {
        $projectId = $this->requireOwnedProjectId($request, $args);

        return $this->json($response, [
            'cards' => array_map($this->present(...), $this->cards->allForProject($projectId)),
        ]);
    }

    /**
     * POST /api/projects/{projectId}/cards
     *
     * Creates the card directly in the project, in its first status (a
     * project card always has one -- see the invariant on the `cards` table).
     */
    public function store(Request $request, Response $response, array $args): Response
    {
        $projectId = $this->requireOwnedProjectId($request, $args);

        $validator = new Validator($this->body($request));
        $text = $validator->requiredString('text', self::TEXT_MAX);
        $complete = $validator->optionalBool('complete') ?? false;
        $position = $validator->optionalInt('position', 0);
        $validator->assert();

        $card = $this->cards->createInProject(
            $this->user($request)['id'],
            $projectId,
            $this->firstStatusId($projectId),
            $text,
            $complete,
            $position,
        );
        $this->projects->touch($projectId);

        return $this->json($response, ['card' => $this->present($card)], 201);
    }

    /**
     * GET /api/inbox/cards
     */
    public function inboxIndex(Request $request, Response $response): Response
    {
        $cards = $this->cards->allInInbox($this->user($request)['id']);

        return $this->json($response, ['cards' => array_map($this->present(...), $cards)]);
    }

    /**
     * POST /api/inbox/cards
     */
    public function inboxStore(Request $request, Response $response): Response
    {
        $validator = new Validator($this->body($request));
        $text = $validator->requiredString('text', self::TEXT_MAX);
        $complete = $validator->optionalBool('complete') ?? false;
        $position = $validator->optionalInt('position', 0);
        $validator->assert();

        $card = $this->cards->createInInbox($this->user($request)['id'], $text, $complete, $position);

        return $this->json($response, ['card' => $this->present($card)], 201);
    }

    /**
     * GET /api/cards/{cardId}
     */
    public function show(Request $request, Response $response, array $args): Response
    {
        return $this->json($response, ['card' => $this->present($this->requireCard($request, $args))]);
    }

    /**
     * PATCH /api/cards/{cardId}
     *
     * Text and completion only. Moving a card -- into/out of the inbox, or
     * between projects -- goes through PUT /api/cards/order.
     */
    public function update(Request $request, Response $response, array $args): Response
    {
        $card = $this->requireCard($request, $args);

        $validator = new Validator($this->body($request));
        $fields = [];
        if ($validator->has('text')) {
            $fields['text'] = $validator->requiredString('text', self::TEXT_MAX);
        }
        if ($validator->has('complete')) {
            $fields['complete'] = $validator->optionalBool('complete');
        }
        if ($fields === [] && !$validator->failed()) {
            $validator->add('text', 'Provide at least one of: text, complete.');
        }
        $validator->assert();

        $updated = $this->cards->update($card['id'], $fields);
        if ($card['project_id'] !== null) {
            $this->projects->touch($card['project_id']);
        }

        return $this->json($response, ['card' => $this->present($updated)]);
    }

    /**
     * DELETE /api/cards/{cardId}
     */
    public function destroy(Request $request, Response $response, array $args): Response
    {
        $card = $this->requireCard($request, $args);
        $this->cards->delete($card['id']);
        if ($card['project_id'] !== null) {
            $this->projects->touch($card['project_id']);
        }

        return $response->withStatus(204);
    }

    /**
     * PUT /api/cards/order
     *
     * Sets the contents and order of one column.
     *
     * Body: { "project_id": 5 | null, "status_id": 2 | null, "card_ids": [3, 1, 2] }
     * -- both null for the inbox, or both set to a project owned by the
     * caller and one of its statuses. `card_ids` are the cards that should
     * make up that column, in order; any card moved in from elsewhere
     * (another project, the inbox) is re-parented and its old column
     * re-packed.
     */
    public function reorder(Request $request, Response $response): Response
    {
        $ownerId = $this->user($request)['id'];
        $body = $this->body($request);

        [$projectId, $statusId] = $this->targetColumn($ownerId, $body);

        $order = $body['card_ids'] ?? null;
        if (!is_array($order) || array_filter($order, static fn ($id) => !is_int($id)) !== []) {
            throw new ApiException('card_ids must be an array of card IDs.', 422);
        }
        /** @var int[] $order */
        if (count($order) !== count(array_unique($order))) {
            throw new ApiException('card_ids must not contain duplicates.', 422);
        }
        if (array_diff($order, $this->cards->idsOwnedBy($ownerId)) !== []) {
            throw new ApiException('Every card_id must be a card you own.', 422);
        }
        if (array_diff($this->cards->idsInColumn($ownerId, $projectId, $statusId), $order) !== []) {
            throw new ApiException('card_ids must include every card already in this column.', 422);
        }

        $cards = $this->cards->orderColumn($ownerId, $projectId, $statusId, $order);

        if ($projectId !== null) {
            $this->projects->touch($projectId);
        }

        return $this->json($response, ['cards' => array_map($this->present(...), $cards)]);
    }

    /**
     * Validate and resolve the { project_id, status_id } target column from
     * the request body.
     *
     * @param array<string, mixed> $body
     * @return array{0: int|null, 1: int|null}
     */
    private function targetColumn(int $ownerId, array $body): array
    {
        $projectId = $body['project_id'] ?? null;
        $statusId = $body['status_id'] ?? null;

        if ($projectId === null) {
            if ($statusId !== null) {
                throw new ApiException('status_id must be null when project_id is null.', 422);
            }

            return [null, null];
        }

        if (!is_int($projectId)) {
            throw new ApiException('project_id must be an integer or null.', 422);
        }
        if ($this->projects->findOwnedBy($projectId, $ownerId) === null) {
            throw new ApiException('Project not found.', 404);
        }
        if (!is_int($statusId)) {
            throw new ApiException('status_id is required when project_id is set.', 422);
        }
        if ($this->statuses->findInProject($statusId, $projectId) === null) {
            throw new ApiException('That status does not belong to this project.', 422);
        }

        return [$projectId, $statusId];
    }

    /** Every project is seeded with statuses on creation; this is never empty. */
    private function firstStatusId(int $projectId): int
    {
        return $this->statuses->allForProject($projectId)[0]['id'];
    }

    /**
     * @param array<string, string> $args
     */
    private function requireOwnedProjectId(Request $request, array $args): int
    {
        $project = $this->projects->findOwnedBy((int) $args['projectId'], $this->user($request)['id']);

        if ($project === null) {
            throw new ApiException('Project not found.', 404);
        }

        return $project['id'];
    }

    /**
     * @param array<string, string> $args
     * @return array{id: int, owner_id: int, project_id: int|null, text: string, complete: bool, position: int, status_id: int|null, status: array{id: int, name: string}|null, created_at: string, updated_at: string}
     */
    private function requireCard(Request $request, array $args): array
    {
        $card = $this->cards->findOwnedBy((int) $args['cardId'], $this->user($request)['id']);

        if ($card === null) {
            throw new ApiException('Card not found.', 404);
        }

        return $card;
    }

    /**
     * @param array{id: int, owner_id: int, project_id: int|null, text: string, complete: bool, position: int, status_id: int|null, status: array{id: int, name: string}|null, created_at: string, updated_at: string} $card
     * @return array<string, mixed>
     */
    private function present(array $card): array
    {
        return [
            'id' => $card['id'],
            'project_id' => $card['project_id'],
            'text' => $card['text'],
            'complete' => $card['complete'],
            'position' => $card['position'],
            'status_id' => $card['status_id'],
            'status' => $card['status'],
            'created_at' => $card['created_at'],
            'updated_at' => $card['updated_at'],
        ];
    }
}