Building Dynamic APIs 🔄

<?php
// A flexible "list" endpoint: the client decides what it gets back through the
// query string. We use an in-memory array so it runs anywhere; in a real app the
// same ideas become WHERE / ORDER BY / LIMIT on a PDO query (see section 4).

// Build a deterministic catalogue so the output is identical every time.
$products = [];
$categories = ['electronics', 'books', 'clothing'];
for ($i = 1; $i <= 50; $i++) {
    $products[] = [
        'id'       => $i,
        'name'     => "Product {$i}",
        'price'    => $i * 10,                 // 10, 20, 30, ...
        'category' => $categories[$i % 3],
    ];
}

// Pretend this came from $_GET on a request like:
//   GET /api/products?category=electronics&min_price=200&sort=price:desc&page=1&per_page=5
$query = [
    'category'  => 'electronics',
    'min_price' => 200,
    'sort'      => 'price:desc',
    'page'      => 1,
    'per_page'  => 5,
];

// 1) FILTER — keep only rows that match the supplied filters.
$rows = $products;
if (!empty($query['category'])) {
    $rows = array_filter($rows, fn($p) => $p['category'] === $query['category']);
}
if (isset($query['min_price'])) {
    $rows = array_filter($rows, fn($p) => $p['price'] >= (int) $query['min_price']);
}
$rows = array_values($rows);                    // re-index after filtering

// 2) SORT — "field:dir", only ALLOW-LISTED fields (never trust raw input).
$sortable = ['price', 'name', 'id'];
[$field, $dir] = array_pad(explode(':', $query['sort'] ?? 'id:asc'), 2, 'asc');
if (in_array($field, $sortable, true)) {        // ignore unknown fields safely
    usort($rows, fn($a, $b) =>
        $dir === 'desc' ? $b[$field] <=> $a[$field] : $a[$field] <=> $b[$field]
    );
}

// 3) PAGINATE — clamp per_page so a client can't ask for 1,000,000 rows.
$total    = count($rows);
$perPage  = min(max((int) ($query['per_page'] ?? 20), 1), 100);   // 1..100
$page     = max((int) ($query['page'] ?? 1), 1);
$pages    = max(1, (int) ceil($total / $perPage));
$offset   = ($page - 1) * $perPage;
$pageRows = array_slice($rows, $offset, $perPage);

echo "Matched {$total} products, showing page {$page} of {$pages}\n";
foreach ($pageRows as $p) {
    echo "  - {$p['name']}  \$" . $p['price'] . "\n";
}

Matched 16 products, showing page 1 of 4
  - Product 49  $490
  - Product 46  $460
  - Product 43  $430
  - Product 40  $400
  - Product 37  $370

<?php
// A list response should carry MORE than just the rows: it needs "meta" so the
// client knows where it is, and "links" so it can move without building URLs.

function paginate(array $items, int $page, int $perPage, string $path): array {
    $total   = count($items);
    $perPage = min(max($perPage, 1), 100);            // clamp: 1..100
    $pages   = max(1, (int) ceil($total / $perPage));
    $page    = min(max($page, 1), $pages);            // clamp into range
    $offset  = ($page - 1) * $perPage;

    // Helper that builds a page URL while preserving per_page.
    $link = fn(int $p) => "{$path}?page={$p}&per_page={$perPage}";

    return [
        'data' => array_slice($items, $offset, $perPage),
        'meta' => [
            'page'        => $page,
            'per_page'    => $perPage,
            'total'       => $total,
            'total_pages' => $pages,
        ],
        'links' => [
            'self'  => $link($page),
            'first' => $link(1),
            'last'  => $link($pages),
            'next'  => $page < $pages ? $link($page + 1) : null,   // null = no more
            'prev'  => $page > 1     ? $link($page - 1) : null,
        ],
    ];
}

$items = array_map(fn($i) => ['id' => $i, 'name' => "Item {$i}"], range(1, 23));
$response = paginate($items, 2, 10, '/api/items');

header('Content-Type: application/json');                 // tell the client it's JSON
echo json_encode($response, JSON_PRETTY_PRINT);

{
    "data": [
        { "id": 11, "name": "Item 11" },
        { "id": 12, "name": "Item 12" }
    ],
    "meta": {
        "page": 2,
        "per_page": 10,
        "total": 23,
        "total_pages": 3
    },
    "links": {
        "self": "/api/items?page=2&per_page=10",
        "first": "/api/items?page=1&per_page=10",
        "last": "/api/items?page=3&per_page=10",
        "next": "/api/items?page=3&per_page=10",
        "prev": "/api/items?page=1&per_page=10"
    }
}

<?php
// Field selection lets the client say "only send me these columns" with ?fields=.
// It shrinks the payload AND protects you from leaking sensitive columns.

$user = [
    'id'            => 7,
    'name'          => 'Alice Smith',
    'email'         => 'alice@example.com',
    'password_hash' => '$2y$10$abc...',     // must NEVER be sent to a client
    'is_admin'      => true,
];

// Only these may ever leave the server. Anything not on the list is invisible.
$publicFields = ['id', 'name', 'email'];

// Client asked: GET /api/users/7?fields=id,name
$requested = explode(',', 'id,name');

// Keep only fields that are BOTH requested AND public (allow-list wins).
$allowed = array_values(array_intersect($requested, $publicFields));
$partial = array_intersect_key($user, array_flip($allowed));

echo "Partial response (?fields=id,name):\n";
echo json_encode($partial, JSON_PRETTY_PRINT) . "\n\n";

// === Search across multiple fields with ?q= ===
$posts = [
    ['id' => 1, 'title' => 'Learning PHP', 'body' => 'PHP powers the web'],
    ['id' => 2, 'title' => 'CSS Grid',     'body' => 'Layout made easy'],
    ['id' => 3, 'title' => 'PHP and JSON', 'body' => 'Encode arrays fast'],
];
$q = 'php';
$hits = array_values(array_filter($posts, function ($p) use ($q) {
    $needle = strtolower($q);
    return str_contains(strtolower($p['title']), $needle)   // case-insensitive
        || str_contains(strtolower($p['body']),  $needle);
}));

echo "Search ?q=php matched " . count($hits) . " posts:\n";
foreach ($hits as $p) {
    echo "  #{$p['id']} {$p['title']}\n";
}

Partial response (?fields=id,name):
{
    "id": 7,
    "name": "Alice Smith"
}

Search ?q=php matched 2 posts:
  #1 Learning PHP
  #3 PHP and JSON

<?php
// 🎯 YOUR TURN — finish the pagination maths, then run it.
// You have 47 items and want page 3 with 10 per page.

$total   = 47;
$page    = 3;
$perPage = 10;

// 1) How many pages are there? (round UP)
$totalPages = ___;          // 👉 max(1, (int) ceil($total / $perPage))

// 2) How many rows do we SKIP to reach this page?
$offset = ___;              // 👉 ($page - 1) * $perPage

// 3) Is there a next page?
$hasNext = ___;             // 👉 $page < $totalPages  (a true/false comparison)

echo "Pages: {$totalPages}, offset: {$offset}, has_next: " . ($hasNext ? 'yes' : 'no') . "\n";

// ✅ Expected output:
//    Pages: 5, offset: 20, has_next: yes
?>

Pages: 5, offset: 20, has_next: yes

<?php
// THE most important pattern in this lesson: build a WHERE clause from optional
// filters WITHOUT ever concatenating user input into the SQL string.
//
// The trick: the COLUMN NAMES come from an allow-list you control, and the
// VALUES go into placeholders (:name) that PDO binds and escapes for you.

function buildProductQuery(array $query): array {
    // Allow-list: maps a safe query-param name -> a real "column operator".
    $filters = [
        'category'  => 'category = :category',
        'min_price' => 'price >= :min_price',
        'max_price' => 'price <= :max_price',
    ];

    $where  = [];   // pieces of SQL, e.g. "price >= :min_price"
    $params = [];   // values to bind, e.g. [':min_price' => 100]

    foreach ($filters as $key => $clause) {
        if (isset($query[$key]) && $query[$key] !== '') {
            $where[]            = $clause;            // SQL text is OURS, never the user's
            $params[":{$key}"]  = $query[$key];      // the VALUE is bound, not pasted
        }
    }

    $sql = 'SELECT id, name, price FROM products';
    if ($where) {
        $sql .= ' WHERE ' . implode(' AND ', $where);
    }

    // Sorting also via an allow-list — you cannot bind a column name.
    $sortable = ['price' => 'price', 'name' => 'name'];
    [$f, $dir] = array_pad(explode(':', $query['sort'] ?? ''), 2, 'asc');
    if (isset($sortable[$f])) {
        $sql .= ' ORDER BY ' . $sortable[$f] . ($dir === 'desc' ? ' DESC' : ' ASC');
    }

    $sql .= ' LIMIT :limit OFFSET :offset';          // always bound a page
    $params[':limit']  = min(max((int) ($query['per_page'] ?? 20), 1), 100);
    $params[':offset'] = (max((int) ($query['page'] ?? 1), 1) - 1) * $params[':limit'];

    return [$sql, $params];
}

// Even a hostile value is harmless — it's bound, never executed as SQL.
[$sql, $params] = buildProductQuery([
    'category'  => "books'; DROP TABLE products; --",
    'min_price' => 10,
    'sort'      => 'price:desc',
    'page'      => 2,
    'per_page'  => 25,
]);

echo $sql . "\n\n";
echo "Bound params:\n";
foreach ($params as $k => $v) {
    echo "  {$k} => " . var_export($v, true) . "\n";
}

// In a real app you'd then run:
//   $stmt = $pdo->prepare($sql);
//   $stmt->execute($params);   // PDO safely binds every value
//   $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);

SELECT id, name, price FROM products WHERE category = :category AND price >= :min_price ORDER BY price DESC LIMIT :limit OFFSET :offset

Bound params:
  :category => 'books\'; DROP TABLE products; --'
  :min_price => 10
  :limit => 25
  :offset => 25

<?php
// 🎯 YOUR TURN — build a SAFE dynamic WHERE clause.
// Only "status" was supplied, so only its clause should appear — and the VALUE
// must be a bound :placeholder, never pasted into the SQL string.

$query = ['status' => 'active'];          // pretend this is $_GET

$allowed = [                              // allow-list of safe filters
    'status'   => 'status = :status',
    'category' => 'category = :category',
];

$where  = [];
$params = [];
foreach ($allowed as $key => $clause) {
    if (isset($query[$key])) {
        $where[]           = ___;         // 👉 the SQL piece, $clause
        $params[":{$key}"] = ___;         // 👉 the VALUE, $query[$key]
    }
}

$sql = 'SELECT * FROM posts';
if ($where) { $sql .= ' WHERE ' . implode(' AND ', $where); }

echo $sql . "\n";
echo "param :status = " . $params[':status'] . "\n";

// ✅ Expected output:
//    SELECT * FROM posts WHERE status = :status
//    param :status = active
?>

SELECT * FROM posts WHERE status = :status
param :status = active

<?php
// API versioning lets you change a response shape WITHOUT breaking old clients.
// Three common places to put the version:
//   1) URL path:      GET /api/v1/users       (most common, cache-friendly, obvious)
//   2) Accept header: Accept: application/vnd.myapp.v2+json
//   3) Query string:  GET /api/users?version=2

function apiV1User(int $id): array {
    return ['id' => $id, 'name' => 'Alice Smith', 'email' => 'alice@example.com'];
}

function apiV2User(int $id): array {
    return [
        'id'         => $id,
        'first_name' => 'Alice',                 // v2 split "name" into two fields
        'last_name'  => 'Smith',
        'email'      => 'alice@example.com',
        'created_at' => '2024-01-15T10:30:00Z',
    ];
}

// ONE envelope for every endpoint = clients write ONE response parser.
function apiResponse(mixed $data, array $meta = [], ?array $errors = null): array {
    return [
        'success' => $errors === null,
        'data'    => $errors === null ? $data : null,
        'errors'  => $errors,
        'meta'    => array_merge(['version' => 'v2'], $meta),
    ];
}

$version = 'v1';                                  // would come from the URL/header
$user    = $version === 'v1' ? apiV1User(1) : apiV2User(1);
echo "GET /api/{$version}/users/1\n";
echo json_encode(apiResponse($user), JSON_PRETTY_PRINT) . "\n\n";

// The SAME envelope carries errors — note success:false and data:null.
echo "Validation error (same shape):\n";
echo json_encode(apiResponse(null, [], [
    ['field' => 'email', 'message' => 'Email is required'],
]), JSON_PRETTY_PRINT);

GET /api/v1/users/1
{
    "success": true,
    "data": {
        "id": 1,
        "name": "Alice Smith",
        "email": "alice@example.com"
    },
    "errors": null,
    "meta": {
        "version": "v2"
    }
}

Validation error (same shape):
{
    "success": false,
    "data": null,
    "errors": [
        {
            "field": "email",
            "message": "Email is required"
        }
    ],
    "meta": {
        "version": "v2"
    }
}