Level 2.B ~25 min Target: PHPStan level 8

Boss: typed repository

A repository is where database rows become domain objects, which makes it the boundary this whole world has been about. Get it right and nothing above it has to wonder whether a price is a string, whether a list has gaps, or whether a product might secretly be null.

This one gets it wrong in every way World 2 covers. Every column arrives as a string, and an @var tag pretends otherwise. A list of mugs comes back keyed by ID. get() promises a Product and can return null. page() returns a Page of who knows what, for page number zero if you ask.

Catalogue (read only) is written against the honest version, and PHPStan reports where the two disagree.

Your checklist

Level	Ask of `ProductRepository`
2.1 array is a shrug	Does every array say what's in it, and is a list really a list?
2.2 Refined scalar types	Do page numbers and prices say which ints they allow?
2.3 Array shapes	Is every raw row converted and checked at the boundary, rather than trusted?
2.4 Type aliases	If you find yourself writing the same shape twice, does it have one name?
2.5 Generics	Does `page()` say what its `Page` holds?
2.6 Narrowing and assertions	Is every `null` dealt with, and every `@var` claim replaced with a check?

Start with Analyse, then work down the checklist. The tests cover the runtime behaviour, including rows that aren't products.

CHALLENGE

ProductRepository hands out whatever the database sends. Prices arrive as strings, a category list is keyed by ID, get() can return null, and hydrate() uses an @var tag to claim the row is already typed.

Bring src/ProductRepository.php up to World 2 standards, so the tests pass and PHPStan is clean at level 8:

find() returns a Product or null, and get() throws ProductNotFound instead of returning null
inCategory() returns a list, in the order the database gives it
page() returns a Page<Product>, and only accepts page numbers and sizes that make sense
every row is converted and checked with Row, and a row that isn't a product throws an UnexpectedValueException

<?php

declare(strict_types=1);

final class ProductRepository
{
    public function __construct(private Db $db) {}

public function find(int $id)
    {
        $row = $this->db->one('SELECT * FROM products WHERE id = ?', [$id]);

return $row ? $this->hydrate($row) : null;
    }

public function get(int $id): Product
    {
        return $this->find($id);
    }

public function inCategory(Category $category): array
    {
        $products = [];
        foreach ($this->db->all('SELECT * FROM products WHERE category = ? ORDER BY name', [$category->value]) as $row) {
            $products[$row['id']] = $this->hydrate($row);
        }

return $products;
    }

public function page(int $page, int $perPage): Page
    {
        $rows = $this->db->all('SELECT * FROM products ORDER BY name LIMIT ? OFFSET ?', [$perPage, ($page - 1) * $perPage]);
        $total = $this->db->count('SELECT COUNT(*) FROM products', []);

return new Page(array_map([$this, 'hydrate'], $rows), $page, $perPage, $total);
    }

private function hydrate(array $row): Product
    {
        /** @var array{id: int, name: string, price_pence: int, category: string} $row */
        return new Product($row['id'], $row['name'], $row['price_pence'], Category::from($row['category']));
    }
}

<?php

declare(strict_types=1);

final class Catalogue
{
    public function __construct(private ProductRepository $products) {}

    /** @return list<non-empty-string> */
    public function names(Category $category): array
    {
        return array_map(fn (Product $product): string => $product->name, $this->products->inCategory($category));
    }

    /**
     * @param positive-int $page
     * @return array{names: list<non-empty-string>, more: bool}
     */
    public function browse(int $page): array
    {
        $results = $this->products->page($page, 20);

        return [
            'names' => array_map(fn (Product $product): string => $product->name, $results->items),
            'more' => $results->hasMore(),
        ];
    }

    /** @return int<0, max> */
    public function priceOf(int $id): int
    {
        return $this->products->get($id)->pricePence;
    }
}

<?php

declare(strict_types=1);

enum Category: string
{
    case Mugs = 'mugs';
    case Tea = 'tea';
}

<?php

declare(strict_types=1);

/** Like PDO, every column comes back as a string. */
interface Db
{
    /**
     * @param list<int|string> $params
     * @return array<string, mixed>|null the first row, or null if there isn't one
     */
    public function one(string $sql, array $params): ?array;

    /**
     * @param list<int|string> $params
     * @return list<array<string, mixed>>
     */
    public function all(string $sql, array $params): array;

    /**
     * @param list<int|string> $params
     * @return int<0, max>
     */
    public function count(string $sql, array $params): int;
}

<?php

declare(strict_types=1);

/**
 * One page of results.
 *
 * @template T
 */
final readonly class Page
{
    /**
     * @param list<T> $items
     * @param positive-int $number
     * @param positive-int $perPage
     * @param int<0, max> $total
     */
    public function __construct(
        public array $items,
        public int $number,
        public int $perPage,
        public int $total,
    ) {}

    public function hasMore(): bool
    {
        return $this->number * $this->perPage < $this->total;
    }
}

<?php

declare(strict_types=1);

final readonly class Product
{
    /**
     * @param non-empty-string $name
     * @param int<0, max> $pricePence
     */
    public function __construct(
        public int $id,
        public string $name,
        public int $pricePence,
        public Category $category,
    ) {}
}

<?php

declare(strict_types=1);

final class ProductNotFound extends RuntimeException {}

<?php

declare(strict_types=1);

/** Converts values from a database row, and refuses anything that doesn't fit. */
final class Row
{
    /** @param array<string, mixed> $row */
    public static function int(array $row, string $key): int
    {
        $value = filter_var($row[$key] ?? null, FILTER_VALIDATE_INT);
        if ($value === false) {
            throw new UnexpectedValueException("$key must be an integer");
        }

        return $value;
    }

    /**
     * @param array<string, mixed> $row
     * @return int<0, max>
     */
    public static function nonNegativeInt(array $row, string $key): int
    {
        $value = filter_var($row[$key] ?? null, FILTER_VALIDATE_INT, ['options' => ['min_range' => 0]]);
        if ($value === false) {
            throw new UnexpectedValueException("$key must be an integer of 0 or more");
        }

        return $value;
    }

    /**
     * @param array<string, mixed> $row
     * @return non-empty-string
     */
    public static function nonEmptyString(array $row, string $key): string
    {
        $value = $row[$key] ?? null;
        if (!is_string($value) || $value === '') {
            throw new UnexpectedValueException("$key must be a non-empty string");
        }

        return $value;
    }
}

Running on PHP 8.3…

Run the tests, run PHPStan, or submit for both. Ctrl/⌘ + Enter submits from the editor.