PHP Architecture 🏗️

<?php
// A VALUE OBJECT wraps a primitive (here a string) so it can NEVER be invalid.
// Once constructed, an Email is guaranteed to be a real email - no defensive
// "is this a valid email?" checks scattered all over your app.

final class Email
{
    // 'readonly' means the value can't change after construction (PHP 8.1+).
    public function __construct(public readonly string $value)
    {
        // Guard clause: reject bad input at the boundary, not deep in the app.
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException("Invalid email: {$value}");
        }
    }

    // Behaviour lives WITH the data - that's what makes it a value object.
    public function domain(): string
    {
        return substr(strrchr($this->value, '@'), 1);  // text after the '@'
    }
}

$email = new Email('ada@example.com');   // valid -> object is created
echo "Address: {$email->value}\n";       // Address: ada@example.com
echo "Domain:  {$email->domain()}\n";    // Domain:  example.com

// Try a bad value and the object refuses to exist:
try {
    new Email('not-an-email');           // throws before any object is returned
} catch (InvalidArgumentException $e) {
    echo "Rejected: {$e->getMessage()}\n";
}

Address: ada@example.com
Domain:  example.com
Rejected: Invalid email: not-an-email

<?php
// A REPOSITORY hides WHERE data lives behind an interface. Your business logic
// asks for a user by id; it never knows (or cares) if that's MySQL, an API,
// or an in-memory array. Swap the storage, the logic stays identical.

interface UserRepository
{
    public function findById(int $id): ?string;   // returns a name, or null
    public function save(int $id, string $name): void;
}

// One concrete implementation - here an in-memory array stands in for a DB.
final class InMemoryUserRepository implements UserRepository
{
    /** @var array<int, string> */
    private array $users = [];

    public function findById(int $id): ?string
    {
        return $this->users[$id] ?? null;     // '??' = "or null if missing"
    }

    public function save(int $id, string $name): void
    {
        $this->users[$id] = $name;
    }
}

$repo = new InMemoryUserRepository();
$repo->save(1, 'Ada Lovelace');               // persist a user

echo $repo->findById(1) . "\n";               // Ada Lovelace
echo ($repo->findById(99) ?? 'not found') . "\n";   // not found

Ada Lovelace
not found

<?php
// The SERVICE LAYER holds your USE CASES (one method = one thing a user can do).
// It DEPENDS ON INTERFACES it is handed in the constructor - that's
// DEPENDENCY INJECTION. The service never builds its own collaborators.

interface UserRepository { public function save(int $id, string $name): void; }
interface Mailer        { public function send(string $to, string $body): void; }

final class InMemoryUserRepository implements UserRepository
{
    public function save(int $id, string $name): void
    {
        echo "[DB] saved user #{$id} ({$name})\n";
    }
}

final class ConsoleMailer implements Mailer
{
    public function send(string $to, string $body): void
    {
        echo "[Mail] to {$to}: {$body}\n";
    }
}

// Pure application logic. Notice: no 'new', no database driver, no mail client.
final class RegisterUser
{
    public function __construct(
        private UserRepository $users,    // injected
        private Mailer $mailer,           // injected
    ) {}

    public function handle(int $id, string $name, string $email): void
    {
        $this->users->save($id, $name);                  // domain action
        $this->mailer->send($email, "Welcome, {$name}!"); // side effect
    }
}

// COMPOSITION ROOT: the one place that wires real implementations together.
// In a framework a DI container does this for you from config.
$action = new RegisterUser(
    new InMemoryUserRepository(),
    new ConsoleMailer(),
);
$action->handle(1, 'Grace Hopper', 'grace@example.com');

[DB] saved user #1 (Grace Hopper)
[Mail] to grace@example.com: Welcome, Grace Hopper!

<?php
// DEPENDENCY INVERSION (the 'D' in SOLID): PaymentService depends on the
// PaymentGateway INTERFACE, never on a concrete Stripe or PayPal class.
// Adding a gateway = one new class. PaymentService never changes (Open/Closed).

interface PaymentGateway
{
    public function charge(int $cents, string $currency): string; // -> tx id
}

final class StripeGateway implements PaymentGateway
{
    public function charge(int $cents, string $currency): string
    {
        return 'stripe_' . strtolower($currency) . '_' . $cents;
    }
}

final class PayPalGateway implements PaymentGateway
{
    public function charge(int $cents, string $currency): string
    {
        return 'paypal_' . strtolower($currency) . '_' . $cents;
    }
}

final class PaymentService
{
    // Constructor injection: the gateway is supplied from outside.
    public function __construct(private PaymentGateway $gateway) {}

    public function pay(int $cents, string $currency): string
    {
        $txId = $this->gateway->charge($cents, $currency);
        echo "Paid {$cents} {$currency} -> tx {$txId}\n";
        return $txId;
    }
}

// Same service, two different gateways - chosen at wiring time, not in the logic.
(new PaymentService(new StripeGateway()))->pay(2999, 'USD');
(new PaymentService(new PayPalGateway()))->pay(4500, 'EUR');

Paid 2999 USD -> tx stripe_usd_2999
Paid 4500 EUR -> tx paypal_eur_4500

<?php
// 🎯 YOUR TURN — finish this DTO (Data Transfer Object).
// A DTO is a small, immutable, TYPED data bag that carries values between
// layers (e.g. controller -> service) so you never pass loose arrays around.

final class CreateOrderDto
{
    public function __construct(
        // 1) Give each property a TYPE and mark it 'readonly' so it can't change.
        public readonly int    $customerId,     // 👉 keep this one as the pattern
        public readonly ___    $product,        // 👉 a product name is text: use  string
        public readonly ___    $quantity,       // 👉 a quantity is a whole number: use  int
    ) {}
}

$order = new CreateOrderDto(customerId: 7, product: 'Keyboard', quantity: 2);

echo "Customer #{$order->customerId}\n";
echo "Wants {$order->quantity} x {$order->product}\n";

// ✅ Expected output:
//    Customer #7
//    Wants 2 x Keyboard

Customer #7
Wants 2 x Keyboard

<?php
// 🎯 YOUR TURN — make this service depend on an INTERFACE, not a class.
// Right now Greeter is hard-wired to EnglishGreeting and can't be swapped.
// Type-hint the INTERFACE so any greeting style can be injected.

interface Greeting { public function text(string $name): string; }

final class EnglishGreeting implements Greeting
{
    public function text(string $name): string { return "Hello, {$name}!"; }
}

final class Greeter
{
    // 👉 Replace ___ with the INTERFACE name so any Greeting can be injected.
    public function __construct(private ___ $greeting) {}

    public function greet(string $name): void
    {
        echo $this->greeting->text($name) . "\n";
    }
}

// Wiring: inject a concrete EnglishGreeting into the Greeter.
(new Greeter(new EnglishGreeting()))->greet('Ada');

// ✅ Expected output:
//    Hello, Ada!

Hello, Ada!