Command i Chain of Responsibility w PHP – wzorce behawioralne

Command enkapsuluje operację jako obiekt – z możliwością kolejkowania, logowania i cofania. Chain of Responsibility przekazuje żądanie przez łańcuch handlerów, gdzie każdy może je obsłużyć lub puścić dalej. Oba wzorce oddzielają „kto zleca” od „kto wykonuje”, co daje dużą elastyczność w układaniu logiki aplikacji.

Command

Wzorzec Command zamienia wywołanie operacji w samodzielny obiekt. Obiekt komendy zawiera wszystkie informacje potrzebne do wykonania operacji: co zrobić, z jakimi danymi i na jakim obiekcie.

<?php

declare(strict_types=1);

// Interfejsy
interface CommandInterface
{
    public function execute(): void;
}

interface UndoableCommandInterface extends CommandInterface
{
    public function undo(): void;
}

// Receiver - obiekt który naprawdę wykonuje pracę
class TextEditor
{
    private string $content = '';
    private int $cursorPosition = 0;

    public function insertText(string $text, int $position): void
    {
        $this->content = substr($this->content, 0, $position)
            . $text
            . substr($this->content, $position);
        $this->cursorPosition = $position + strlen($text);
    }

    public function deleteText(int $position, int $length): string
    {
        $deleted = substr($this->content, $position, $length);
        $this->content = substr($this->content, 0, $position)
            . substr($this->content, $position + $length);
        $this->cursorPosition = $position;
        return $deleted;
    }

    public function getContent(): string { return $this->content; }
}

<?php

declare(strict_types=1);

// Konkretne komendy - każda enkapsuluje jedną operację
class InsertTextCommand implements UndoableCommandInterface
{
    public function __construct(
        private TextEditor $editor,
        private string $text,
        private int $position
    ) {}

    public function execute(): void
    {
        $this->editor->insertText($this->text, $this->position);
    }

    public function undo(): void
    {
        $this->editor->deleteText($this->position, strlen($this->text));
    }
}

class DeleteTextCommand implements UndoableCommandInterface
{
    private string $deletedText = '';

    public function __construct(
        private TextEditor $editor,
        private int $position,
        private int $length
    ) {}

    public function execute(): void
    {
        // Zapamiętaj usunięty tekst dla undo()
        $this->deletedText = $this->editor->deleteText($this->position, $this->length);
    }

    public function undo(): void
    {
        $this->editor->insertText($this->deletedText, $this->position);
    }
}

// Invoker - zarządza kolejką komend i historią
class CommandHistory
{
    /** @var UndoableCommandInterface[] */
    private array $history = [];

    /** @var UndoableCommandInterface[] */
    private array $redoStack = [];

    public function execute(CommandInterface $command): void
    {
        $command->execute();

        if ($command instanceof UndoableCommandInterface) {
            $this->history[]  = $command;
            $this->redoStack  = []; // nowa komenda czyści redo stack
        }
    }

    public function undo(): void
    {
        if (empty($this->history)) {
            return;
        }

        $command = array_pop($this->history);
        $command->undo();
        $this->redoStack[] = $command;
    }

    public function redo(): void
    {
        if (empty($this->redoStack)) {
            return;
        }

        $command = array_pop($this->redoStack);
        $command->execute();
        $this->history[] = $command;
    }

    public function getHistoryCount(): int { return count($this->history); }
}

// Użycie
$editor  = new TextEditor();
$history = new CommandHistory();

$history->execute(new InsertTextCommand($editor, 'Witaj świecie', 0));
echo $editor->getContent(); // Witaj świecie

$history->execute(new InsertTextCommand($editor, '! ', 13));
echo $editor->getContent(); // Witaj świecie! 

$history->execute(new DeleteTextCommand($editor, 0, 5));
echo $editor->getContent(); //  świecie! 

$history->undo(); // cofnij DeleteText
echo $editor->getContent(); // Witaj świecie! 

$history->undo(); // cofnij drugi InsertText
echo $editor->getContent(); // Witaj świecie

$history->redo(); // ponów InsertText
echo $editor->getContent(); // Witaj świecie! 

Command w kolejkowaniu zadań – asynchroniczne wykonanie:

<?php

declare(strict_types=1);

// Komenda serializowalna - do wysłania w kolejce
class SendEmailCommand implements CommandInterface
{
    public function __construct(
        public readonly string $to,
        public readonly string $subject,
        public readonly string $body
    ) {}

    public function execute(): void
    {
        // W kontekście consumera - wstrzyknięty serwis mailowy wykonuje pracę
        echo "Wysyłam email do {$this->to}: {$this->subject}\n";
    }
}

// CommandBus - dispatcher który może działać sync lub async
class CommandBus
{
    private array $queue = [];

    public function dispatch(CommandInterface $command): void
    {
        $command->execute(); // wykonaj natychmiast
    }

    public function dispatchAsync(CommandInterface $command): void
    {
        $this->queue[] = $command; // dodaj do kolejki
    }

    public function processQueue(): void
    {
        while (!empty($this->queue)) {
            $command = array_shift($this->queue);
            $command->execute();
        }
    }
}

$bus = new CommandBus();
$bus->dispatchAsync(new SendEmailCommand('jan@example.com', 'Temat', 'Treść'));
$bus->dispatchAsync(new SendEmailCommand('anna@example.com', 'Temat 2', 'Treść 2'));
$bus->processQueue(); // przetwórz wszystkie naraz

Chain of Responsibility

Chain of Responsibility przekazuje żądanie przez łańcuch potencjalnych handlerów. Każdy handler decyduje czy obsłuży żądanie czy przekaże dalej. Sender nie wie który handler faktycznie przetworzy żądanie.

<?php

declare(strict_types=1);

// Interfejs handlera
interface MiddlewareInterface
{
    public function setNext(MiddlewareInterface $middleware): MiddlewareInterface;
    public function handle(Request $request): ?Response;
}

// Abstrakcyjny handler - obsługuje łańcuchowanie
abstract class AbstractMiddleware implements MiddlewareInterface
{
    private ?MiddlewareInterface $next = null;

    public function setNext(MiddlewareInterface $middleware): MiddlewareInterface
    {
        $this->next = $middleware;
        return $middleware; // fluent - można chainować setNext()->setNext()
    }

    public function handle(Request $request): ?Response
    {
        if ($this->next !== null) {
            return $this->next->handle($request);
        }

        return null; // koniec łańcucha bez obsługi
    }
}

// Prosty DTO dla przykładu
class Request
{
    public function __construct(
        public readonly string $method,
        public readonly string $path,
        public readonly array $headers = [],
        public readonly ?string $body = null
    ) {}
}

class Response
{
    public function __construct(
        public readonly int $status,
        public readonly string $body
    ) {}
}

<?php

// Konkretne handlery - middleware pipeline HTTP
class AuthenticationMiddleware extends AbstractMiddleware
{
    private array $validTokens = ['secret-token-123', 'admin-token-456'];

    public function handle(Request $request): ?Response
    {
        $authHeader = $request->headers['Authorization'] ?? '';

        if (!str_starts_with($authHeader, 'Bearer ')) {
            return new Response(401, 'Unauthorized: Missing token');
        }

        $token = substr($authHeader, 7);

        if (!in_array($token, $this->validTokens, true)) {
            return new Response(401, 'Unauthorized: Invalid token');
        }

        echo "Auth: token poprawny\n";
        return parent::handle($request); // przekaż dalej
    }
}

class RateLimitMiddleware extends AbstractMiddleware
{
    private array $requestCounts = [];
    private int $maxRequests;

    public function __construct(int $maxRequestsPerMinute = 60)
    {
        $this->maxRequests = $maxRequestsPerMinute;
    }

    public function handle(Request $request): ?Response
    {
        $ip    = $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1';
        $count = ($this->requestCounts[$ip] ?? 0) + 1;
        $this->requestCounts[$ip] = $count;

        if ($count > $this->maxRequests) {
            return new Response(429, 'Too Many Requests');
        }

        echo "RateLimit: {$count}/{$this->maxRequests} requestów\n";
        return parent::handle($request);
    }
}

class LoggingMiddleware extends AbstractMiddleware
{
    public function handle(Request $request): ?Response
    {
        echo "Log: {$request->method} {$request->path}\n";
        $response = parent::handle($request);
        echo "Log: odpowiedź " . ($response?->status ?? 'brak') . "\n";
        return $response;
    }
}

class RouterMiddleware extends AbstractMiddleware
{
    private array $routes = [];

    public function addRoute(string $method, string $path, callable $handler): void
    {
        $this->routes["{$method}:{$path}"] = $handler;
    }

    public function handle(Request $request): ?Response
    {
        $key     = "{$request->method}:{$request->path}";
        $handler = $this->routes[$key] ?? null;

        if ($handler === null) {
            return new Response(404, 'Not Found');
        }

        return $handler($request);
    }
}

// Budowanie łańcucha middleware
$router = new RouterMiddleware();
$router->addRoute('GET', '/api/products', fn($req) => new Response(200, '{"products":[]}'));
$router->addRoute('POST', '/api/orders',  fn($req) => new Response(201, '{"order_id":42}'));

$auth      = new AuthenticationMiddleware();
$rateLimit = new RateLimitMiddleware(100);
$logging   = new LoggingMiddleware();

// Łańcuch: Logging -> RateLimit -> Auth -> Router
$logging
    ->setNext($rateLimit)
    ->setNext($auth)
    ->setNext($router);

// Testy
$validRequest = new Request('GET', '/api/products', ['Authorization' => 'Bearer secret-token-123']);
$response     = $logging->handle($validRequest);
echo "Status: {$response->status}\n\n";

$invalidAuth = new Request('GET', '/api/products', ['Authorization' => 'Bearer wrong-token']);
$response    = $logging->handle($invalidAuth);
echo "Status: {$response->status}\n";

Command vs Chain of Responsibility

Podsumowanie

Command i Chain of Responsibility to wzorce które błyszczą w architekturze warstw pośrednich. Command jest podstawą każdego systemu kolejkowania zadań – obiekt komendy jest serializowalny, może być przekazany między procesami i wykonany asynchronicznie. Chain of Responsibility to naturalny wzorzec dla middleware HTTP – każdy handler robi jedną rzecz i albo odpowiada albo przekazuje dalej. Oba wzorce mocno wspierają Open/Closed Principle: dodajesz nową komendę albo nowy handler do łańcucha bez zmiany istniejącego kodu.