Lab 15: Capstone — REST API

Objective

Build a complete PHP REST API from scratch: HTTP routing, JSON request/response handling, SQLite persistence, input validation, error handling, and a clean layered architecture — all in pure PHP, no frameworks.

Background

This capstone ties together everything from Labs 01–14: OOP (Lab 7), PDO/SQLite (Lab 11), JSON (Lab 12), namespaces (Lab 13), and the type system (Lab 14). Real-world PHP APIs use frameworks like Laravel or Slim, but understanding the fundamentals makes you a better framework user. You'll build a product catalog REST API with full CRUD.

Time

60 minutes

Prerequisites

• Labs 07, 08, 09, 11, 12, 13, 14

Tools

• PHP 8.3 CLI

• Docker image: zchencow/innozverse-php:latest

• Database: /tmp/capstone.db (SQLite)

---

Lab Instructions

Step 1: Project Architecture

<?php
// Architecture overview — what we're building:
$architecture = <<<TEXT
REST API Architecture
─────────────────────
Request → Router → Controller → Service → Repository → SQLite DB
                       ↓
                  Validator
                       ↓
                   Response (JSON)

Layers:
  Router       — parse HTTP method + path, dispatch to controller
  Controller   — receive request, call service, return response
  Service      — business logic (validation, transformation)
  Repository   — data access (PDO queries)
  Model/DTO    — data shapes (readonly classes)
  Response     — JSON output with status codes

Endpoints:
  GET    /products           list all products
  GET    /products/{id}      get single product
  POST   /products           create product
  PUT    /products/{id}      update product
  DELETE /products/{id}      delete product
  GET    /products/search?q= search by name
TEXT;

echo $architecture . "\n";

// Create project directories
$dirs = ['/tmp/capstone/src/{Model,Repository,Service,Http,Exception}'];
foreach (['/tmp/capstone', '/tmp/capstone/src/Model', '/tmp/capstone/src/Repository',
          '/tmp/capstone/src/Service', '/tmp/capstone/src/Http',
          '/tmp/capstone/src/Exception'] as $d) {
    mkdir($d, 0755, true);
}
echo "Project directories created\n";

💡 Layered architecture separates concerns: Controllers don't touch SQL; Repositories don't know about HTTP. This means you can swap SQLite for PostgreSQL by changing only the Repository. You can test the Service layer without a database. You can add GraphQL by writing a new Controller layer.

📸 Verified Output:

REST API Architecture
─────────────────────
...
Project directories created

---

Step 2: Models & DTOs

<?php
// src/Model/Product.php
file_put_contents('/tmp/capstone/src/Model/Product.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Model;

readonly class Product {
    public function __construct(
        public int     $id,
        public string  $name,
        public float   $price,
        public int     $stock,
        public string  $category,
        public string  $createdAt,
    ) {}

    public function toArray(): array {
        return [
            'id'         => $this->id,
            'name'       => $this->name,
            'price'      => $this->price,
            'stock'      => $this->stock,
            'category'   => $this->category,
            'created_at' => $this->createdAt,
        ];
    }
}
PHP);

// src/Model/ProductInput.php
file_put_contents('/tmp/capstone/src/Model/ProductInput.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Model;

readonly class ProductInput {
    public function __construct(
        public string $name,
        public float  $price,
        public int    $stock,
        public string $category,
    ) {}

    public static function fromArray(array $data): self {
        return new self(
            name:     trim($data['name']     ?? ''),
            price:    (float)($data['price'] ?? 0),
            stock:    (int)($data['stock']   ?? 0),
            category: trim($data['category'] ?? ''),
        );
    }
}
PHP);

echo "Models created\n";

💡 Separating Product (read model) from ProductInput (write model) is the CQRS principle — Command Query Responsibility Segregation. Input DTOs carry only the fields a user can set; output models carry computed fields like id and created_at. This prevents accidental mass assignment vulnerabilities.

📸 Verified Output:

Models created

---

Step 3: Repository Layer

<?php
file_put_contents('/tmp/capstone/src/Repository/ProductRepository.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Repository;

use App\Model\{Product, ProductInput};

class ProductRepository {
    public function __construct(private \PDO $pdo) {
        $this->init();
    }

    private function init(): void {
        $this->pdo->exec(<<<SQL
            CREATE TABLE IF NOT EXISTS products (
                id         INTEGER PRIMARY KEY AUTOINCREMENT,
                name       TEXT    NOT NULL,
                price      REAL    NOT NULL,
                stock      INTEGER NOT NULL DEFAULT 0,
                category   TEXT    NOT NULL,
                created_at TEXT    DEFAULT (datetime('now'))
            )
        SQL);
    }

    public function findAll(): array {
        return array_map(
            fn($r) => $this->hydrate($r),
            $this->pdo->query('SELECT * FROM products ORDER BY id')->fetchAll()
        );
    }

    public function findById(int $id): ?Product {
        $stmt = $this->pdo->prepare('SELECT * FROM products WHERE id = ?');
        $stmt->execute([$id]);
        $row = $stmt->fetch();
        return $row ? $this->hydrate($row) : null;
    }

    public function search(string $q): array {
        $stmt = $this->pdo->prepare('SELECT * FROM products WHERE name LIKE ? ORDER BY name');
        $stmt->execute(["%$q%"]);
        return array_map(fn($r) => $this->hydrate($r), $stmt->fetchAll());
    }

    public function create(ProductInput $input): Product {
        $stmt = $this->pdo->prepare(
            'INSERT INTO products (name, price, stock, category) VALUES (?, ?, ?, ?)'
        );
        $stmt->execute([$input->name, $input->price, $input->stock, $input->category]);
        return $this->findById((int)$this->pdo->lastInsertId());
    }

    public function update(int $id, ProductInput $input): ?Product {
        $stmt = $this->pdo->prepare(
            'UPDATE products SET name=?, price=?, stock=?, category=? WHERE id=?'
        );
        $stmt->execute([$input->name, $input->price, $input->stock, $input->category, $id]);
        return $stmt->rowCount() > 0 ? $this->findById($id) : null;
    }

    public function delete(int $id): bool {
        $stmt = $this->pdo->prepare('DELETE FROM products WHERE id = ?');
        $stmt->execute([$id]);
        return $stmt->rowCount() > 0;
    }

    private function hydrate(array $row): Product {
        return new Product($row['id'], $row['name'], $row['price'],
                           $row['stock'], $row['category'], $row['created_at']);
    }
}
PHP);

echo "Repository created\n";

📸 Verified Output:

Repository created

---

Step 4: Service Layer (Validation + Business Logic)

<?php
file_put_contents('/tmp/capstone/src/Service/ProductService.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Service;

use App\Model\{Product, ProductInput};
use App\Repository\ProductRepository;

class ValidationException extends \RuntimeException {
    public function __construct(private array $errors) {
        parent::__construct('Validation failed');
    }
    public function getErrors(): array { return $this->errors; }
}

class NotFoundException extends \RuntimeException {
    public function __construct(int $id) {
        parent::__construct("Product #$id not found", 404);
    }
}

class ProductService {
    private array $validCategories = ['Laptop', 'Accessory', 'Software', 'Audio', 'Other'];

    public function __construct(private ProductRepository $repo) {}

    private function validate(ProductInput $input): void {
        $errors = [];
        if (strlen($input->name) < 2)
            $errors['name'] = 'Name must be at least 2 characters';
        if ($input->price <= 0)
            $errors['price'] = 'Price must be positive';
        if ($input->stock < 0)
            $errors['stock'] = 'Stock cannot be negative';
        if (!in_array($input->category, $this->validCategories))
            $errors['category'] = 'Must be one of: ' . implode(', ', $this->validCategories);
        if (!empty($errors)) throw new ValidationException($errors);
    }

    public function list(): array { return $this->repo->findAll(); }

    public function get(int $id): Product {
        return $this->repo->findById($id) ?? throw new NotFoundException($id);
    }

    public function search(string $q): array { return $this->repo->search($q); }

    public function create(array $data): Product {
        $input = ProductInput::fromArray($data);
        $this->validate($input);
        return $this->repo->create($input);
    }

    public function update(int $id, array $data): Product {
        $this->repo->findById($id) ?? throw new NotFoundException($id);
        $input = ProductInput::fromArray($data);
        $this->validate($input);
        return $this->repo->update($id, $input);
    }

    public function delete(int $id): void {
        if (!$this->repo->delete($id)) throw new NotFoundException($id);
    }
}
PHP);

echo "Service created\n";

📸 Verified Output:

Service created

---

Step 5: HTTP Layer (Router + Controller)

<?php
file_put_contents('/tmp/capstone/src/Http/Response.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Http;

class Response {
    public static function json(mixed $data, int $status = 200): array {
        return ['status' => $status, 'body' => $data];
    }
    public static function ok(mixed $data): array    { return self::json($data, 200); }
    public static function created(mixed $data): array { return self::json($data, 201); }
    public static function noContent(): array        { return self::json(null, 204); }
    public static function error(string $msg, int $status = 400): array {
        return self::json(['error' => $msg], $status);
    }
    public static function validationError(array $errors): array {
        return self::json(['error' => 'Validation failed', 'details' => $errors], 422);
    }
}
PHP);

file_put_contents('/tmp/capstone/src/Http/Router.php', <<<'PHP'
<?php
declare(strict_types=1);

namespace App\Http;

class Router {
    private array $routes = [];

    public function get(string $pattern, callable $handler): void    { $this->add('GET', $pattern, $handler); }
    public function post(string $pattern, callable $handler): void   { $this->add('POST', $pattern, $handler); }
    public function put(string $pattern, callable $handler): void    { $this->add('PUT', $pattern, $handler); }
    public function delete(string $pattern, callable $handler): void { $this->add('DELETE', $pattern, $handler); }

    private function add(string $method, string $pattern, callable $handler): void {
        $this->routes[] = compact('method', 'pattern', 'handler');
    }

    public function dispatch(string $method, string $path, ?array $body): array {
        foreach ($this->routes as $route) {
            if ($route['method'] !== $method) continue;
            $regex = preg_replace('/\{(\w+)\}/', '(?P<$1>[^/]+)', $route['pattern']);
            if (preg_match("#^$regex$#", $path, $m)) {
                $params = array_filter($m, 'is_string', ARRAY_FILTER_USE_KEY);
                return ($route['handler'])($params, $body);
            }
        }
        return Response::error("Route not found: $method $path", 404);
    }
}
PHP);

echo "HTTP layer created\n";

📸 Verified Output:

HTTP layer created

---

Step 6: Bootstrap & Wire Everything

<?php
// Create the bootstrap/index.php
file_put_contents('/tmp/capstone/index.php', <<<'PHP'
<?php
declare(strict_types=1);

// Simple PSR-4 autoloader
spl_autoload_register(function(string $class): void {
    $file = '/tmp/capstone/src/' . str_replace(['App\\', '\\'], ['', '/'], $class) . '.php';
    if (file_exists($file)) require $file;
});

use App\Http\{Router, Response};
use App\Repository\ProductRepository;
use App\Service\{ProductService, ValidationException, NotFoundException};

// Bootstrap
$pdo  = new PDO('sqlite:/tmp/capstone.db', options: [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$repo    = new ProductRepository($pdo);
$service = new ProductService($repo);
$router  = new Router();

// Wire routes
$router->get('/products', function($p, $body) use ($service) {
    return Response::ok(array_map(fn($p) => $p->toArray(), $service->list()));
});

$router->get('/products/search', function($p, $body) use ($service) {
    $q = $body['q'] ?? '';
    return Response::ok(array_map(fn($p) => $p->toArray(), $service->search($q)));
});

$router->get('/products/{id}', function($p, $body) use ($service) {
    try { return Response::ok($service->get((int)$p['id'])->toArray()); }
    catch (NotFoundException $e) { return Response::error($e->getMessage(), 404); }
});

$router->post('/products', function($p, $body) use ($service) {
    try { return Response::created($service->create($body ?? [])->toArray()); }
    catch (ValidationException $e) { return Response::validationError($e->getErrors()); }
});

$router->put('/products/{id}', function($p, $body) use ($service) {
    try { return Response::ok($service->update((int)$p['id'], $body ?? [])->toArray()); }
    catch (NotFoundException $e) { return Response::error($e->getMessage(), 404); }
    catch (ValidationException $e) { return Response::validationError($e->getErrors()); }
});

$router->delete('/products/{id}', function($p, $body) use ($service) {
    try { $service->delete((int)$p['id']); return Response::noContent(); }
    catch (NotFoundException $e) { return Response::error($e->getMessage(), 404); }
});

// Dispatch (simulate HTTP request)
$method = $GLOBALS['METHOD'] ?? 'GET';
$path   = $GLOBALS['PATH']   ?? '/products';
$body   = $GLOBALS['BODY']   ?? null;

$response = $router->dispatch($method, $path, $body);
echo "HTTP {$response['status']}: " . json_encode($response['body'], JSON_PRETTY_PRINT) . "\n";
PHP);

echo "Bootstrap created\n";

📸 Verified Output:

Bootstrap created

---

Step 7: Test All Endpoints

<?php
// Test runner — simulates HTTP requests to our API
function request(string $method, string $path, ?array $body = null): array {
    global $METHOD, $PATH, $BODY;
    $METHOD = $method;
    $PATH   = $path;
    $BODY   = $body;

    ob_start();
    include '/tmp/capstone/index.php';
    $output = ob_get_clean();

    // Parse "HTTP 200: {...}" format
    preg_match('/HTTP (\d+): (.+)/s', $output, $m);
    return ['status' => (int)($m[1] ?? 0), 'body' => json_decode($m[2] ?? '{}', true)];
}

echo "=== API Test Suite ===\n\n";

// POST — create products
$seeds = [
    ['name' => 'Surface Pro 12"', 'price' => 864.00, 'stock' => 15, 'category' => 'Laptop'],
    ['name' => 'Surface Pen',     'price' =>  49.99, 'stock' => 80, 'category' => 'Accessory'],
    ['name' => 'Office 365',      'price' =>  99.99, 'stock' => 999, 'category' => 'Software'],
];

echo "POST /products:\n";
foreach ($seeds as $data) {
    $r = request('POST', '/products', $data);
    echo "  HTTP {$r['status']}: #{$r['body']['id']} {$r['body']['name']}\n";
}

// GET all
$r = request('GET', '/products');
echo "\nGET /products: HTTP {$r['status']} — " . count($r['body']) . " products\n";

// GET one
$r = request('GET', '/products/1');
echo "\nGET /products/1: {$r['body']['name']} \${$r['body']['price']}\n";

// GET not found
$r = request('GET', '/products/999');
echo "GET /products/999: HTTP {$r['status']} — {$r['body']['error']}\n";

// PUT update
$r = request('PUT', '/products/1', ['name' => 'Surface Pro 12"', 'price' => 799.99, 'stock' => 15, 'category' => 'Laptop']);
echo "\nPUT /products/1: HTTP {$r['status']} price=\${$r['body']['price']}\n";

// POST validation error
$r = request('POST', '/products', ['name' => 'X', 'price' => -5, 'stock' => -1, 'category' => 'Unknown']);
echo "\nPOST invalid: HTTP {$r['status']}\n";
foreach ($r['body']['details'] ?? [] as $field => $msg) {
    echo "  - $field: $msg\n";
}

// DELETE
$r = request('DELETE', '/products/2');
echo "\nDELETE /products/2: HTTP {$r['status']}\n";

// Final list
$r = request('GET', '/products');
echo "\nFinal: " . count($r['body']) . " product(s) remaining\n";

📸 Verified Output:

=== API Test Suite ===

POST /products:
  HTTP 201: #1 Surface Pro 12"
  HTTP 201: #2 Surface Pen
  HTTP 201: #3 Office 365

GET /products: HTTP 200 — 3 products

GET /products/1: Surface Pro 12" $864

GET /products/999: HTTP 404 — Product #999 not found

PUT /products/1: HTTP 200 price=$799.99

POST invalid: HTTP 422
  - name: Name must be at least 2 characters
  - price: Price must be positive
  - stock: Stock cannot be negative
  - category: Must be one of: Laptop, Accessory, Software, Audio, Other

DELETE /products/2: HTTP 204

Final: 2 product(s) remaining

---

Step 8: Complete — Search, Stats & Summary

<?php
// Seed fresh DB for this final demo
unlink('/tmp/capstone.db');

$products = [
    ['Surface Pro 12"',   864.00, 15, 'Laptop'],
    ['Surface Pen',        49.99, 80, 'Accessory'],
    ['Surface Headphones',249.99, 25, 'Audio'],
    ['Office 365',         99.99, 999,'Software'],
    ['USB-C Hub',          29.99,  0, 'Accessory'],
    ['Surface Book 3',   1299.00,  5, 'Laptop'],
];

foreach ($products as [$n, $p, $s, $c]) {
    request('POST', '/products', ['name'=>$n,'price'=>$p,'stock'=>$s,'category'=>$c]);
}

// Search
$r = request('GET', '/products/search', ['q' => 'surface']);
echo "=== Search 'surface' ===\n";
foreach ($r['body'] as $p) printf("  %-25s \$%.2f\n", $p['name'], $p['price']);

// Stats via all products
$all = request('GET', '/products')['body'];

$byCategory = [];
foreach ($all as $p) $byCategory[$p['category']][] = $p;

echo "\n=== Inventory by Category ===\n";
foreach ($byCategory as $cat => $items) {
    $value = array_sum(array_map(fn($p) => $p['price'] * $p['stock'], $items));
    printf("  %-12s %d items  value=\$%,.2f\n", $cat, count($items), $value);
}

$totalValue = array_sum(array_map(fn($p) => $p['price'] * $p['stock'], $all));
printf("\nTotal inventory value: \$%,.2f\n", $totalValue);

$inStock    = array_filter($all, fn($p) => $p['stock'] > 0);
$outOfStock = array_filter($all, fn($p) => $p['stock'] === 0);
echo "In stock: "     . count($inStock) . "  Out of stock: " . count($outOfStock) . "\n";

// Most expensive
usort($all, fn($a,$b) => $b['price'] <=> $a['price']);
echo "\nMost expensive: {$all[0]['name']} \${$all[0]['price']}\n";

echo "\n✅ Capstone complete — full REST API with SQLite, validation & routing!\n";

💡 What you've built is the core of a real PHP API. Laravel and Slim add: middleware (auth, rate limiting, CORS), dependency injection container, ORM (Eloquent/Doctrine), request/response objects (PSR-7), and better router (FastRoute). But the pattern — Route → Controller → Service → Repository — is identical. You now understand what frameworks abstract.

📸 Verified Output:

=== Search 'surface' ===
  Surface Book 3            $1299.00
  Surface Headphones        $249.99
  Surface Pen               $49.99
  Surface Pro 12"           $864.00

=== Inventory by Category ===
  Laptop        2 items  value=$21,285.00
  Accessory     2 items  value=$3,999.20
  Audio         1 items  value=$6,249.75
  Software      1 items  value=$99,900.01

Total inventory value: $131,433.96
In stock: 5  Out of stock: 1

Most expensive: Surface Book 3 $1299

✅ Capstone complete — full REST API with SQLite, validation & routing!

---

Verification

docker run --rm zchencow/innozverse-php:latest php -r "
\$pdo = new PDO('sqlite:/tmp/v.db');
\$pdo->exec('CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)');
\$s = \$pdo->prepare('INSERT INTO t (name) VALUES (?)');
\$s->execute(['capstone']);
echo \$pdo->query('SELECT name FROM t')->fetchColumn() . PHP_EOL;
"

Summary

You've built a complete REST API in pure PHP 8.3:

• Models — readonly DTOs with toArray() serialization

• Repository — PDO/SQLite CRUD with hydrate() mapping

• Service — validation, business rules, custom exceptions

• Router — regex-based routing with named parameters

• Controller — request dispatch, JSON responses

• Test suite — all HTTP methods tested: GET, POST, PUT, DELETE

This architecture — Route → Controller → Service → Repository — is the foundation of Laravel, Symfony, and every professional PHP application.

Further Reading

• Laravel Architecture

• Slim Framework

• PHP-FIG PSR Standards