Level 5.B ~25 min Target: PHPStan max

Boss: a returns desk

Returning all three mugs from a discounted order refunds £5.01 on a £5.00 order. Not much, until it's every discounted order for a year. Finance wants the penny back. The returns page has already been redesigned around better types. The returns desk behind it hasn't.

ReturnsDesk::quote() works out refunds in float pounds, finds orders by asking a global container, decides whether the 30 days are up with whatever new DateTime() says today is, and ignores a SKU it doesn't recognise. None of it is new. This is World 5 in one method.

Your checklist

Level	Ask of `ReturnsDesk`
5.1 Value objects	Does it take an `OrderReference`, so normalising and checking happen once, before it's called?
5.2 Money	Is every amount `Money` in integer pence, with the discount allocated so the shares add up?
5.3 Immutable all the way down	Are dates `DateTimeImmutable`, and is every `modify()` result used?
5.4 Dependency injection	Does it ask for orders and the time in its constructor, rather than fetching them?
5.5 Small interfaces	Does it depend on the smallest interface it needs, so a test's fake has one method?

The tests use a one-method fake for the orders and a stopped clock, so the desk has to accept both. ShopServices passes the real DatabaseOrderRepository, which implements the big OrderRepository. Both fit, if you pick the right interface.

CHALLENGE

The returns desk quotes refunds as floats, so returning all three mugs from a discounted order gives back a penny more than the customer paid. It fetches orders from a global container, reads the real time through a mutable DateTime, and quietly ignores SKUs that aren't on the order.

Bring src/ReturnsDesk.php up to World 5 standards, so the tests pass and PHPStan is clean at max. ReturnsController and ShopServices (both read only) are already written against the result:

quote() takes an OrderReference and returns Money in the order's currency
each line's share of the discount comes from Money::allocate(), by line price, so a whole order refunds exactly what was paid
the constructor takes the smallest interface that can find an order, and a Clock
a SKU that isn't on the order throws an InvalidArgumentException, like an unknown order

<?php

declare(strict_types=1);

final class ReturnsDesk
{
    /**
     * What the customer gets back, in pounds, for returning these SKUs. Returns are accepted
     * until the end of the 30th day after the order. Each line refunds its price, less its
     * share of the order's discount.
     *
     * @param list<string> $skus
     */
    public function quote(string $reference, array $skus): float
    {
        $orders = Container::get('orders');
        $order = $orders->find(OrderReference::fromString($reference));
        if ($order === null) {
            throw new InvalidArgumentException("No order {$reference}");
        }

$lastDay = DateTime::createFromImmutable($order->placedOn);
        $lastDay->modify('+30 days');
        $lastDay->setTime(23, 59, 59);
        if (new DateTime() > $lastDay) {
            return 0.0;
        }

$subtotal = 0;
        foreach ($order->lines as $line) {
            $subtotal += $line->price->pence;
        }

$refund = 0.0;
        foreach ($order->lines as $line) {
            if (in_array($line->sku, $skus, true)) {
                $share = round($order->discount->pence * $line->price->pence / $subtotal / 100, 2);
                $refund += $line->price->pence / 100 - $share;
            }
        }

return round($refund, 2);
    }
}

<?php

declare(strict_types=1);

/** The returns page. It's already written against the redesigned ReturnsDesk. */
final readonly class ReturnsController
{
    public function __construct(private ReturnsDesk $desk) {}

    /** @param list<string> $skus as ticked on the form */
    public function quote(string $reference, array $skus): string
    {
        $refund = $this->desk->quote(OrderReference::fromString($reference), $skus);

        return "You'll get {$refund->format()} back.";
    }
}

<?php

declare(strict_types=1);

/** The composition root: the one place that picks the real orders and the real clock. */
final class ShopServices
{
    public static function returnsController(): ReturnsController
    {
        return new ReturnsController(new ReturnsDesk(new DatabaseOrderRepository(), new SystemClock()));
    }
}

<?php

declare(strict_types=1);

final readonly class Order
{
    /** @param non-empty-list<Line> $lines */
    public function __construct(
        public OrderReference $reference,
        public DateTimeImmutable $placedOn,
        public array $lines,
        public Money $discount, // off the whole order
    ) {}
}

<?php

declare(strict_types=1);

final readonly class Line
{
    public function __construct(
        public string $sku,
        public Money $price,
    ) {}
}

<?php

declare(strict_types=1);

final readonly class OrderReference
{
    private function __construct(public string $value) {}

    public static function fromString(string $reference): self
    {
        $reference = strtoupper(trim($reference));
        if (preg_match('/^R-\d+$/', $reference) !== 1) {
            throw new InvalidArgumentException("Not an order reference: '{$reference}'");
        }

        return new self($reference);
    }

    public function equals(self $other): bool
    {
        return $this->value === $other->value;
    }
}

<?php

declare(strict_types=1);

interface Orders
{
    public function find(OrderReference $reference): ?Order;
}

<?php

declare(strict_types=1);

interface OrderRepository extends Orders
{
    /** @return list<Order> */
    public function placedBetween(DateTimeImmutable $from, DateTimeImmutable $to): array;

    /** @return list<Order> */
    public function forCustomer(string $email): array;

    public function save(Order $order): void;

    public function cancel(Order $order): void;

    public function countToday(): int;
}

<?php

declare(strict_types=1);

/**
 * The real repository talks to MySQL. Its queries are left out here: what matters
 * is that it implements every method of OrderRepository.
 */
final class DatabaseOrderRepository implements OrderRepository
{
    public function find(OrderReference $reference): ?Order { throw self::needsTheDatabase(); }

    public function placedBetween(DateTimeImmutable $from, DateTimeImmutable $to): array { throw self::needsTheDatabase(); }

    public function forCustomer(string $email): array { throw self::needsTheDatabase(); }

    public function save(Order $order): void { throw self::needsTheDatabase(); }

    public function cancel(Order $order): void { throw self::needsTheDatabase(); }

    public function countToday(): int { throw self::needsTheDatabase(); }

    private static function needsTheDatabase(): LogicException
    {
        return new LogicException("There's no database in the sandbox");
    }
}

<?php

declare(strict_types=1);

final readonly class Money
{
    public function __construct(
        public int $pence, // or cents: the currency's smallest unit
        public Currency $currency,
    ) {}

    public function plus(Money $other): self
    {
        if ($other->currency !== $this->currency) {
            throw new InvalidArgumentException("Can't add {$other->currency->value} to {$this->currency->value}");
        }

        return new self($this->pence + $other->pence, $this->currency);
    }

    public function minus(Money $other): self
    {
        return $this->plus(new self(-$other->pence, $other->currency));
    }

    /**
     * Splits this amount in proportion to the ratios. The shares always add up to the whole.
     *
     * @return list<Money>
     */
    public function allocate(int ...$ratios): array
    {
        $ratios = array_values($ratios);
        $total = array_sum($ratios);
        if ($ratios === [] || $total <= 0 || min($ratios) < 0) {
            throw new InvalidArgumentException('Allocate needs ratios of 0 or more, adding up to more than 0');
        }

        $roundedDown = array_map(fn (int $ratio): int => intdiv($this->pence * $ratio, $total), $ratios);
        $left = $this->pence - array_sum($roundedDown);

        $shares = [];
        foreach ($roundedDown as $i => $pence) {
            // Hand out what's left a penny at a time, from the first share.
            $shares[] = new self($i < abs($left) ? $pence + ($left <=> 0) : $pence, $this->currency);
        }

        return $shares;
    }

    public function equals(Money $other): bool
    {
        return $this->pence === $other->pence && $this->currency === $other->currency;
    }

    public function format(): string
    {
        return sprintf('%s%d.%02d', $this->currency->symbol(), intdiv($this->pence, 100), $this->pence % 100);
    }
}

<?php

declare(strict_types=1);

enum Currency: string
{
    case GBP = 'GBP';
    case EUR = 'EUR';

    public function symbol(): string
    {
        return match ($this) {
            self::GBP => '£',
            self::EUR => '€',
        };
    }
}

<?php

declare(strict_types=1);

interface Clock
{
    public function now(): DateTimeImmutable;
}

<?php

declare(strict_types=1);

final class SystemClock implements Clock
{
    public function now(): DateTimeImmutable
    {
        return new DateTimeImmutable();
    }
}

<?php

declare(strict_types=1);

/** A global service locator: anything can ask it for anything, and gets back mixed. */
final class Container
{
    /** @var array<string, mixed> */
    private static array $services = [];

    public static function set(string $id, mixed $service): void
    {
        self::$services[$id] = $service;
    }

    public static function get(string $id): mixed
    {
        return self::$services[$id] ?? throw new RuntimeException("No service called '{$id}' has been set");
    }
}

Running on PHP 8.3…

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