Add stage 3: todo list and item CRUD API

Two migrations add todo_lists (owner_id FK to users, title, description) and todo_items (list_id FK, text, complete, position), both with ON DELETE CASCADE. New endpoints under /api/lists, all behind AuthMiddleware: - lists: index / store / show / update (PATCH) / destroy - items: nested under a list, same five verbs Lists are owner-scoped — another user's or a missing list responds 404, never 403. New items append after the highest position unless one is given; the list carries item_count / completed_count. Item PATCH is partial and never renumbers siblings. Adds App\Support\Validator for request-body checks, TodoList/TodoItem repositories, and body()/user() helpers on the Controller base. Feature tests move their shared harness into tests/ApiTestCase; TodoTest covers CRUD, ownership isolation, ordering, completion counts, validation and cascade delete. Full suite: 15 passing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-03 18:30:52 +01:00
parent 5e3b8dbd7e
commit 5a0d29a308
12 changed files with 1093 additions and 4 deletions
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Http\Controllers;

 use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;

 /**
 * Shared helpers for HTTP controllers.
@@ -26,4 +27,29 @@ abstract class Controller
            ->withHeader('Content-Type', 'application/json')
            ->withStatus($status);
    }
+
+    /**
+     * The parsed JSON request body as an array (empty when absent or not an object).
+     *
+     * @return array<string, mixed>
+     */
+    protected function body(Request $request): array
+    {
+        $parsed = $request->getParsedBody();
+
+        return is_array($parsed) ? $parsed : [];
+    }
+
+    /**
+     * The authenticated user attached by AuthMiddleware.
+     *
+     * @return array{id: int, email: string, email_verified_at: string|null, created_at: string}
+     */
+    protected function user(Request $request): array
+    {
+        /** @var array{id: int, email: string, email_verified_at: string|null, created_at: string} $user */
+        $user = $request->getAttribute('user');
+
+        return $user;
+    }
 }
@@ -0,0 +1,156 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Exception\ApiException;
+use App\Repository\TodoItemRepository;
+use App\Repository\TodoListRepository;
+use App\Support\Validator;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+
+/**
+ * CRUD for the items within one todo list. Every route first checks that the
+ * parent list is owned by the authenticated user; otherwise it responds 404.
+ */
+final class TodoItemController extends Controller
+{
+    private const TEXT_MAX = 1000;
+
+    public function __construct(
+        private readonly TodoListRepository $lists,
+        private readonly TodoItemRepository $items,
+    ) {
+    }
+
+    /**
+     * GET /api/lists/{listId}/items
+     */
+    public function index(Request $request, Response $response, array $args): Response
+    {
+        $listId = $this->requireOwnedListId($request, $args);
+
+        return $this->json($response, [
+            'items' => array_map($this->present(...), $this->items->allForList($listId)),
+        ]);
+    }
+
+    /**
+     * POST /api/lists/{listId}/items
+     */
+    public function store(Request $request, Response $response, array $args): Response
+    {
+        $listId = $this->requireOwnedListId($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();
+
+        $item = $this->items->create($listId, $text, $complete, $position);
+        $this->lists->touch($listId);
+
+        return $this->json($response, ['item' => $this->present($item)], 201);
+    }
+
+    /**
+     * GET /api/lists/{listId}/items/{itemId}
+     */
+    public function show(Request $request, Response $response, array $args): Response
+    {
+        $listId = $this->requireOwnedListId($request, $args);
+
+        return $this->json($response, ['item' => $this->present($this->requireItem($listId, $args))]);
+    }
+
+    /**
+     * PATCH /api/lists/{listId}/items/{itemId}
+     */
+    public function update(Request $request, Response $response, array $args): Response
+    {
+        $listId = $this->requireOwnedListId($request, $args);
+        $item = $this->requireItem($listId, $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 ($validator->has('position')) {
+            $fields['position'] = $validator->optionalInt('position', 0);
+        }
+        if ($fields === [] && !$validator->failed()) {
+            $validator->add('text', 'Provide at least one of: text, complete, position.');
+        }
+        $validator->assert();
+
+        $updated = $this->items->update($item['id'], $listId, $fields);
+        $this->lists->touch($listId);
+
+        return $this->json($response, ['item' => $this->present($updated)]);
+    }
+
+    /**
+     * DELETE /api/lists/{listId}/items/{itemId}
+     */
+    public function destroy(Request $request, Response $response, array $args): Response
+    {
+        $listId = $this->requireOwnedListId($request, $args);
+        $this->items->delete($this->requireItem($listId, $args)['id']);
+        $this->lists->touch($listId);
+
+        return $response->withStatus(204);
+    }
+
+    /**
+     * @param array<string, string> $args
+     */
+    private function requireOwnedListId(Request $request, array $args): int
+    {
+        $list = $this->lists->findOwnedBy((int) $args['listId'], $this->user($request)['id']);
+
+        if ($list === null) {
+            throw new ApiException('List not found.', 404);
+        }
+
+        return $list['id'];
+    }
+
+    /**
+     * @param array<string, string> $args
+     * @return array{id: int, list_id: int, text: string, complete: bool, position: int, created_at: string, updated_at: string}
+     */
+    private function requireItem(int $listId, array $args): array
+    {
+        $item = $this->items->findInList((int) $args['itemId'], $listId);
+
+        if ($item === null) {
+            throw new ApiException('Item not found.', 404);
+        }
+
+        return $item;
+    }
+
+    /**
+     * @param array{id: int, list_id: int, text: string, complete: bool, position: int, created_at: string, updated_at: string} $item
+     * @return array<string, mixed>
+     */
+    private function present(array $item): array
+    {
+        return [
+            'id' => $item['id'],
+            'list_id' => $item['list_id'],
+            'text' => $item['text'],
+            'complete' => $item['complete'],
+            'position' => $item['position'],
+            'created_at' => $item['created_at'],
+            'updated_at' => $item['updated_at'],
+        ];
+    }
+}
@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Exception\ApiException;
+use App\Repository\TodoListRepository;
+use App\Support\Validator;
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+
+/**
+ * CRUD for the authenticated user's todo lists. A list is only ever visible to
+ * its owner; anything else responds 404.
+ */
+final class TodoListController extends Controller
+{
+    private const TITLE_MAX = 255;
+    private const DESCRIPTION_MAX = 2000;
+
+    public function __construct(private readonly TodoListRepository $lists)
+    {
+    }
+
+    /**
+     * GET /api/lists
+     */
+    public function index(Request $request, Response $response): Response
+    {
+        $lists = $this->lists->allForOwner($this->user($request)['id']);
+
+        return $this->json($response, ['lists' => array_map($this->present(...), $lists)]);
+    }
+
+    /**
+     * POST /api/lists
+     */
+    public function store(Request $request, Response $response): Response
+    {
+        $validator = new Validator($this->body($request));
+        $title = $validator->requiredString('title', self::TITLE_MAX);
+        $description = $validator->optionalString('description', self::DESCRIPTION_MAX) ?? '';
+        $validator->assert();
+
+        $list = $this->lists->create($this->user($request)['id'], $title, $description);
+
+        return $this->json($response, ['list' => $this->present($list)], 201);
+    }
+
+    /**
+     * GET /api/lists/{listId}
+     */
+    public function show(Request $request, Response $response, array $args): Response
+    {
+        return $this->json($response, ['list' => $this->present($this->requireOwnedList($request, $args))]);
+    }
+
+    /**
+     * PATCH /api/lists/{listId}
+     */
+    public function update(Request $request, Response $response, array $args): Response
+    {
+        $list = $this->requireOwnedList($request, $args);
+
+        $validator = new Validator($this->body($request));
+        $fields = [];
+        if ($validator->has('title')) {
+            $fields['title'] = $validator->requiredString('title', self::TITLE_MAX);
+        }
+        if ($validator->has('description')) {
+            $fields['description'] = $validator->optionalString('description', self::DESCRIPTION_MAX) ?? '';
+        }
+        if ($fields === [] && !$validator->failed()) {
+            $validator->add('title', 'Provide at least one of: title, description.');
+        }
+        $validator->assert();
+
+        $updated = $this->lists->update($list['id'], $list['owner_id'], $fields);
+
+        return $this->json($response, ['list' => $this->present($updated)]);
+    }
+
+    /**
+     * DELETE /api/lists/{listId}
+     */
+    public function destroy(Request $request, Response $response, array $args): Response
+    {
+        $this->lists->delete($this->requireOwnedList($request, $args)['id']);
+
+        return $response->withStatus(204);
+    }
+
+    /**
+     * Load the list named in the route, or 404 if it is missing or not owned by
+     * the authenticated user.
+     *
+     * @param array<string, string> $args
+     * @return array{id: int, owner_id: int, title: string, description: string, item_count: int, completed_count: int, created_at: string, updated_at: string}
+     */
+    private function requireOwnedList(Request $request, array $args): array
+    {
+        $list = $this->lists->findOwnedBy((int) $args['listId'], $this->user($request)['id']);
+
+        if ($list === null) {
+            throw new ApiException('List not found.', 404);
+        }
+
+        return $list;
+    }
+
+    /**
+     * @param array{id: int, owner_id: int, title: string, description: string, item_count: int, completed_count: int, created_at: string, updated_at: string} $list
+     * @return array<string, mixed>
+     */
+    private function present(array $list): array
+    {
+        return [
+            'id' => $list['id'],
+            'title' => $list['title'],
+            'description' => $list['description'],
+            'owner_id' => $list['owner_id'],
+            'item_count' => $list['item_count'],
+            'completed_count' => $list['completed_count'],
+            'created_at' => $list['created_at'],
+            'updated_at' => $list['updated_at'],
+        ];
+    }
+}