Architektura Symfony dla złożonych aplikacji PHP: moduły, Messenger i integracje

Symfony sprawdza się, gdy aplikacja PHP wyrasta poza zbiór kontrolerów i integracji. Framework daje zespołowi jawne granice — HTTP, walidację, serializację, komunikację i konfigurację — bez narzucania jednego kształtu całemu produktowi. Wartość pojawia się wtedy, gdy te granice pozostają czytelne po wielu latach działania systemu.

Wybierz Symfony według kształtu problemu

Mała aplikacja CRUD nie potrzebuje rozbudowanej architektury. Symfony ma sens, gdy system ma kilka domen biznesowych, długowieczne integracje, workflow asynchroniczne albo zespół chce używać komponentów poza pełnym monolitem. Decyzja powinna wynikać z tych ograniczeń, a nie z samej preferencji frameworka.

Publiczna aplikacja DigiSpace jest oparta na Laravel, dlatego ten tekst jest przewodnikiem technicznym, a nie opisem produkcyjnego repozytorium Symfony. Wzorce wynikają z oficjalnych komponentów Symfony i z tych samych problemów widocznych w naszej pracy z PHP: jawna walidacja requestów, cienkie kontrolery, testowalne serwisy, kolejki, zewnętrzne API i wdrożenia z możliwością rollbacku.

Niech warstwa HTTP będzie prosta

Kontroler Symfony powinien tłumaczyć HTTP request na application command, a wynik na HTTP response. Nie powinien decydować, jak liczyć fakturę, jak ponawiać wywołanie providera ani jak koordynować transakcję. Te decyzje należą do application services lub handlers, które można testować bez uruchamiania całego kernela.

final class CreateOrderController
{
    public function __construct(
        private CreateOrderHandler $handler,
    ) {}

    public function __invoke(CreateOrderRequest $request): JsonResponse
    {
        $order = $this->handler->handle(
            new CreateOrderCommand(
                customerId: $request->customerId(),
                lines: $request->lines(),
            ),
        );

        return new JsonResponse(['id' => $order->id()], Response::HTTP_CREATED);
    }
}

Najważniejsza jest granica. Walidacja może odrzucić błędny input na brzegu, a handler pracuje z command o znanym kształcie. Dzięki temu późniejsze przejście z synchronicznego kontrolera na message handler jest mniej inwazyjne.

Organizuj kod wokół domen, nie folderów

Symfony nie narzuca jednego layoutu katalogów. W rosnącym systemie organizuj kod wokół możliwości biznesowych, takich jak Orders, Billing czy Catalog. Moduł może zawierać application commands, domain rules, infrastructure adapters i HTTP entry points. Ważniejsze od nazw folderów jest to, aby kierunek zależności był jasny.

Moduł domenowy nie powinien wiedzieć, czy email wysłał Symfony Mailer, worker kolejki czy test double. Powinien wyrazić event albo command. Infrastruktura decyduje, jak wiadomość podróżuje. Dzięki temu zmiana providera staje się ograniczonym zadaniem zamiast przeszukiwania wszystkich kontrolerów.

Użyj Messenger, gdy request powinien zakończyć się szybciej

Symfony Messenger obsługuje zarówno natychmiastowe przetwarzanie, jak i transporty wykonujące wiadomości później. Zespół może zacząć od synchronicznego message busa, a wybrane zadania przenieść do kolejki, gdy uzasadnia to latency lub sposób obsługi błędów. Message to mały, serializowalny opis pracy, a handler posiada side effect.

final readonly class GenerateInvoice
{
    public function __construct(public string $invoiceId) {}
}

#[AsMessageHandler]
final class GenerateInvoiceHandler
{
    public function __invoke(GenerateInvoice $message): void
    {
        // Pobierz fakturę, wyrenderuj PDF, zapisz go i powiadom użytkownika.
    }
}

Praca w tle wymaga operational policy. Skonfiguruj retry dla przejściowych błędów providera, failure transport dla wiadomości, których nadal nie da się obsłużyć, oraz idempotency rule, aby ponowienie nie utworzyło podwójnej płatności ani powiadomienia. Kolejka jest mechanizmem dostarczenia, nie gwarancją bezpieczeństwa nieidempotentnej operacji.

Schowaj systemy zewnętrzne za adapterami

Symfony HttpClient daje spójną abstrakcję klienta, ale formaty odpowiedzi providera nie powinny przenikać do application code. Utwórz mały adapter mapujący request i response providera na własne value objects. Timeouty, uwierzytelnianie, retry policy i logging trzymaj w adapterze albo jego konfiguracji transportu.

Jest to szczególnie przydatne dla płatności, synchronizacji CRM i webhooków. Aplikacja może testować awarię providera bez jego wywoływania, a adapter może mieć osobny contract test z sandboxem. Gdy provider zmienia payload, najpierw zmienia się jedna granica.

Uczyń konfigurację i sekrety jawnymi

Długo działające systemy Symfony często psują się na konfiguracji: worker ma inne środowisko, komenda CLI nie widzi sekretu albo endpoint stagingowy trafia do produkcji. Traktuj konfigurację jak input aplikacji. Sprawdzaj wymagane wartości przy starcie, trzymaj sekrety poza repozytorium, a środowisko workera wpisz do checklisty wdrożenia.

Nie chowaj decyzji operacyjnych w static globals. Typowany configuration object albo injected parameter pokazuje zależność w konstruktorze i czyni założenia testu czytelnymi.

Testuj kontrakty, które mają znaczenie

Testy jednostkowe są przydatne dla domain rules, ale nie zastępują HTTP i integration tests. Praktyczny zestaw Symfony ma trzy poziomy: szybkie testy obliczeń i polityk, application tests dla command i handler behaviour oraz mniejszy zestaw testów HTTP dla routingu, walidacji i serializacji. Testy integracyjne powinny obejmować granice, na których można zgubić dane: kolejki, webhooki, bazy i klientów zewnętrznych.

Podczas modernizacji istniejącej aplikacji PHP characterization tests są bezpiecznym początkiem. Zapisz aktualną odpowiedź i side effects przed przeniesieniem kodu. Następnie wymieniaj jeden moduł lub integrację naraz i zostaw odwracalną trasę albo feature switch.

Planuj deployment z uwzględnieniem workerów i wiadomości

Wdrożenia Symfony mają szczegół, którego nie widać w zwykłym HTTP deploymencie: workery są długo działające. Nowy release może zawierać zmienioną klasę message albo handler, podczas gdy stary worker nadal ma załadowany poprzedni kod. Restartuj workery w ramach release, używaj kompatybilnych zmian wiadomości przy rolling deploy i obserwuj failure transport po aktywacji.

Migracje bazy powinny najpierw być addytywne. Dodaj kolumnę albo tabelę, wdroż kod czytający obie wersje, wykonaj backfill, a dopiero w kolejnym release usuń compatibility code. Dzięki temu rollback nie zależy od stanu bazy, którego już nie ma.

Co to podejście daje biznesowi

Modułowość obniża koszt pracy równoległej i wyjaśnia odpowiedzialność. Messenger usuwa wolną lub zawodną pracę z user request. Adaptery ograniczają zmianę providera. Jawna konfiguracja i restart workerów zmniejszają klasę incydentów „działa tylko w jednym środowisku”. To praktyczne korzyści, które nie wymagają obietnicy, że Symfony usunie całą złożoność.

Kiedy lepszy będzie Laravel albo same komponenty

Nie wybieraj Symfony automatycznie. Laravel może być szybszy dla produktu, który korzysta z jego konwencji i zintegrowanych narzędzi. Mniejszy system może potrzebować tylko komponentów Symfony — HttpClient, Messenger albo Serializer — bez całego frameworka. Właściwa odpowiedź to najmniejszy zestaw granic, który utrzyma reguły biznesowe w jasności, a ryzyka operacyjne w polu widzenia.

Opis usługi znajdziesz na stronie Tworzenie aplikacji w Symfony. Jeśli wybierasz między Symfony, Laravel albo pojedynczymi komponentami, zacznij od domen, trybów awarii integracji i cyklu życia workerów.