Zaczynamy budowę bloga od zera. Poznamy stack (Symfony 8, PHP 8.4, PostgreSQL 16, Docker), uruchomimy środowisko, omówimy strukturę katalogów i konwencje, których będziemy się trzymać przez cały tutorial (dwie warstwy kontrolerów, DTO w API, ręczny CRUD).

Czego się nauczysz

Stack: Symfony 8, PHP 8.4, PostgreSQL 16, Twig, Vite
Uruchomienie środowiska w Dockerze (make start, db-init)
Struktura katalogów src/ i templates/
Konwencje projektu: dwie warstwy kontrolerów, DTO, ręczny CRUD

Rozdział 1: Instalacja i konfiguracja

Witaj w tutorialu budowy bloga na Symfony 8. Zbudujemy go stopniowo, w pięciu częściach:

Część I — Blog podstawowy (rozdziały 1–8): fundament (User), encje, lista, strona artykułu, kategorie i tagi, komentarze, panel admina. Po niej masz działający blog.
Część II — Bogata treść i media (9–13): Markdown z kolorowaniem kodu, obrazki, wideo/audio, upload, PDF.
Część III — Wielojęzyczność (14–15): tłumaczenia artykułów i kategorii.
Część IV — API (16–17): publiczne REST API i API admina.
Część V — Jakość i wdrożenie (18–20): testy i deployment z SEO.

Tutorial jest tak pomyślany, byś mógł zatrzymać się po Części I i mieć gotowy projekt, a kolejne części dołożyć później.

Dziś przygotujemy środowisko i poznamy konwencje, których będziemy się trzymać.

Jak zbudowany jest ten tutorial: każdy rozdział to praktyczny krok, który kończy się sprawdzalnym efektem. Kod jest kompletny i gotowy do wklejenia — możesz go odtworzyć u siebie krok po kroku.

Stack

Blog stoi na tym samym, nowoczesnym stacku co cały projekt:

Warstwa	Technologia
Framework	Symfony 8.0 / PHP 8.4
Baza danych	PostgreSQL 16 przez Doctrine ORM 3
Szablony	Twig 3
Frontend	Vite + Stimulus + Turbo (Symfony UX)
Markdown	league/commonmark (treść artykułów)
Paginacja	Pagerfanta
API	REST + NelmioApiDoc (Swagger `/api/doc`)
Środowisko	pełny Docker (PHP-FPM, Nginx, PostgreSQL, Mailpit)

Świadomie nie używamy gotowych „generatorów panelu” (EasyAdmin, Sonata) ani API Platform — panel i API piszemy ręcznie, żeby mieć pełną kontrolę i pokazać, jak działają pod spodem.

Uruchomienie środowiska

Całość działa w Dockerze — nie musisz instalować PHP ani PostgreSQL lokalnie. Do zarządzania służy make:

make start       # zbuduj obrazy i wystartuj kontenery
make db-init     # migracje + dane testowe (fixtures)

Po chwili narzędzia środowiska są dostępne pod:

Usługa	URL
Aplikacja	http://localhost:8090
Web Profiler	http://localhost:8090/_profiler
Mailpit (podgląd maili)	http://localhost:8025
Adminer (GUI bazy)	http://localhost:8091

Blog (/blog) i dokumentacja API (/api/doc) pojawią się dopiero, gdy zbudujemy odpowiednie warstwy — listę artykułów w Rozdziale 4, a API w Części IV.

Polecenia konsoli Symfony uruchamiamy w kontenerze app:

docker compose exec app php bin/console <komenda>

Restart środowiska po zatrzymaniu:

make stop && make fast && make db-init

Struktura projektu

Kod bloga rozłożony jest według warstw. Najważniejsze katalogi:

src/
├── Controller/            # kontrolery webowe (Twig) — BlogController
│   └── Admin/             # panel admina — BlogAdminController
├── Api/                   # warstwa REST API
│   ├── Controller/        # BlogApiController, BlogAdminApiController
│   └── Dto/               # BlogArticleDto, BlogCategoryDto, BlogTagDto
├── Entity/                # encje Doctrine — BlogArticle, BlogCategory, BlogTag, BlogComment…
├── Form/                  # typy formularzy — BlogArticleType…
├── Repository/            # repozytoria Doctrine — BlogArticleRepository…
└── Service/              # logika biznesowa — BlogSlugResolver…

templates/
├── blog/                  # front bloga — index.html.twig, show.html.twig
└── admin/blog/            # panel admina

Konwencje projektu

Trzy zasady, które przewijają się przez cały tutorial — warto je zapamiętać od początku:

Dwie warstwy kontrolerów. src/Controller/ renderuje szablony Twig (front i panel admina). src/Api/Controller/ zwraca JSON. To rozdzielenie utrzymujemy konsekwentnie.
W API nigdy nie serializujemy encji Doctrine. Zawsze zwracamy DTO (BlogArticleDto::fromEntity). Dzięki temu kształt odpowiedzi API jest niezależny od modelu bazy (Część IV).
Panel admina piszemy ręcznie. Zwykły CRUD na formularzach Symfony, z auto-slug-iem i ochroną ROLE_ADMIN — bez EasyAdmin (Część I, rozdział 8).

Bogatą treść, wielojęzyczność, API oraz testy i deploy dokładamy dopiero w Częściach II–V, jako rozszerzenia — podstawowy blog działa bez nich.

Weryfikacja

Sprawdź, że środowisko stoi:

docker compose ps                       # kontenery w stanie "running"
docker compose exec app php bin/console about   # wersja Symfony/PHP

Wejdź na http://localhost:8090 — powinna pojawić się strona startowa aplikacji (bez błędu 500). To Twój działający stan po tym rozdziale: uruchomione środowisko. Bloga (/blog) zbudujemy dopiero od Rozdziału 4, a użytkowników testowych — w Rozdziale 2.

Zasada tutoriala: każdy rozdział kończy się czymś działającym, co możesz sprawdzić, zanim przejdziesz dalej. Dzięki temu blog rośnie krok po kroku, a każdy krok da się dołożyć osobno.

Podsumowanie

Środowisko gotowe, konwencje ustalone:

✅ stack: Symfony 8 / PHP 8.4 / PostgreSQL 16 / Docker, front na Vite, treść w markdown,
✅ uruchomienie przez make start + make db-init, aplikacja pod localhost:8090,
✅ struktura src/ (dwie warstwy kontrolerów, Api/Dto, Entity, Repository, Service),
✅ trzy konwencje: dwie warstwy kontrolerów, DTO w API, ręczny CRUD (bez EasyAdmin/API Platform).

W Rozdziale 2 zbudujemy fundament — encję User, bezpieczeństwo i użytkowników testowych, na których opiera się cały blog (autor artykułu, komentujący, panel admina).

Instalacja i konfiguracja