Część 5 opisywała jak Claude Code był używany podczas początkowego budowania — AGENTS.md jako instrukcja obsługi dla AI, generowanie serwisów i szablonów z konwencji, tłumaczenie treści. Ten wpis opisuje co dzieje się później: strona działa, build przechodzi, ale architektura ma niedociągnięcia. Trzy rundy poprawek jakości, ekstrakcja komponentów i reorganizacja namespace'ów — wszystko napędzane cyklami przeglądów z pomocą AI.

Dlaczego iterować?#

Pierwsza działająca wersja priorytetyzuje wysyłkę. Opublikuj treść, niech build przejdzie, wdróż na Raspberry Pi. Dług techniczny narasta naturalnie po drodze: metody zwracają tablice asocjacyjne zamiast value objects, serwisy wstrzykiwane są jako klasy konkretne zamiast interfejsów, szablony rosną w monolity.

W zespole code review wyłapuje te wzorce. W solowym projekcie nie ma nikogo do przeglądania pull requestów. AI wypełnia tę lukę — nie jako pieczątka akceptacji, ale jako systematyczny reviewer czytający każdy plik i raportujący problemy z numerami linii.

Cykl iteracji:

1. Poproś AI o audyt pod kątem konkretnych wzorców (strict types, naruszenia SOLID, problemy DRY)
2. AI czyta każdy plik PHP, raportuje problemy ze ścieżkami plików i numerami linii
3. Zaplanuj poprawki w pliku .plans/ z checkboxami
4. Implementuj fazami, weryfikuj ddev code-check po każdej
5. Powtórz z kolejnym fokusem jakościowym

Każda runda ma konkretny zakres. Próba naprawienia wszystkiego naraz prowadzi do szumnych diffów i przeoczonych regresji. Skupione rundy produkują dające się przejrzeć i zweryfikować zmiany.

Runda 1 — Value Objects zamiast tablic#

Pierwsza runda celowała w własną zasadę projektu: "Nigdy nie zwracaj tablic asocjacyjnych dla złożonych danych."

Problem#

MarkdownParser::parse() zwracał tablicę:

// Przed
public function parse(string $markdown): array
{
    // ...
    return [
        'frontMatter' => $frontMatter,
        'html' => $html,
    ];
}

// Konsument
$result = $this->parser->parse($content);
$frontMatter = $result['frontMatter'];  // brak bezpieczeństwa typów
$html = $result['html'];               // literówka = cichy bug

Ten sam wzorzec dla nawigacji sąsiednich wpisów — ContentTree::getAdjacentPosts() zwracał ['prev' => $post, 'next' => $post].

Problemy: brak bezpieczeństwa typów, brak autouzupełniania w IDE, PHPStan nie wyłapie literówki w $result['htlm'].

Poprawka#

final readonly class ParsedMarkdown
{
    /** @param array<string, mixed> $frontMatter */
    public function __construct(
        public array $frontMatter,
        public string $html,
    ) {
    }
}

final readonly class AdjacentPosts
{
    public function __construct(
        public ?ContentItem $prev,
        public ?ContentItem $next,
    ) {
    }
}

Teraz parser zwraca ParsedMarkdown, konsument odwołuje się do $parsed->frontMatter i $parsed->html, a PHPStan wyłapuje każdą literówkę w nazwie właściwości na etapie analizy.

Siedem value objects zostało utworzonych lub przeniesionych w tej rundzie:

Wszystkie są readonly, używają constructor property promotion i żyją w src/Content/ValueObject/.

Runda 2 — interfejsy dla wszystkiego#

Druga runda wymusiła kolejną zasadę projektu: "Każda wstrzykiwana klasa w src/Service/ musi mieć odpowiadający interfejs."

Problem#

Dwa serwisy wstrzykiwane były jako klasy konkretne:

// Przed
public function __construct(
    private readonly ContentTreeBuilder $builder,
    private readonly MarkdownParser $parser,
) {
}

Działało, ale naruszało zasadę odwrócenia zależności. Reszta bazy kodu już wstrzykiwała przez interfejsy (ContentServiceInterface, ImageResizerInterface). Te dwa były wyjątkami.

Poprawka#

interface MarkdownParserInterface
{
    public function parse(string $markdown): ParsedMarkdown;
}

interface ContentTreeBuilderInterface
{
    public function build(string $locale): ContentTree;
}

// Po
public function __construct(
    private readonly ContentTreeBuilderInterface $builder,
    private readonly MarkdownParserInterface $parser,
) {
}

Klasy konkretne implementują interfejsy. Autowiring Symfony obsługuje powiązanie. Zasada jest teraz wymuszona wszędzie: 12 interfejsów serwisów w 4 podkatalogach.

src/Service/
├── Content/
│   ├── ContentServiceInterface + ContentService
│   ├── ContentTreeBuilderInterface + ContentTreeBuilder
│   ├── MarkdownParserInterface + MarkdownParser
│   ├── SidebarDataProviderInterface + SidebarDataProvider
│   └── TranslationMapBuilderInterface + TranslationMapBuilder
├── Image/
│   ├── ImageResizerInterface + ImageResizer
│   └── ResponsiveImageServiceInterface + ResponsiveImageService
├── Preview/
│   ├── DraftPreviewServiceInterface + DraftPreviewService
│   └── ScheduledPreviewServiceInterface + ScheduledPreviewService
├── SiteConfigServiceInterface + SiteConfigService
└── TurnstileValidatorInterface + TurnstileValidator

Dodatkowa zasada z tej rundy: stałe należą do interfejsu, nie do klasy konkretnej. Klasa konkretna dziedziczy je przez self::CONSTANT_NAME.

Runda 3 — eliminacja zakodowanych wartości#

Trzecia runda celowała w subtelniejszy problem: wartości, które działają dziś, ale rozjadą się jutro.

Zakodowane URL-e w szablonach#

Przełącznik języka miał zakodowane ścieżki archiwum:

{# Przed — psuje się gdy routing się zmieni #}
{% set url = locale is same as('pl') ? '/archive/' : '/pl/archiwum/' %}

{# Po — używa nazwanych tras #}
{% set url = path('blog_archive_' ~ other, {year: archive_year, month: '%02d'|format(archive_month)}) %}

Ten sam wzorzec w BlogController dla przełączania tagów między locale — zakodowane /pl/tag/ i /blog/ zastąpione przez $this->generateUrl('blog_tag_'.$otherLocale, ...).

Zakodowane progi obrazów#

Szablon responsywnych obrazów miał szerokości srcset zakodowane jako stringi. Gdyby zmienna środowiskowa IMAGE_VARIANT_WIDTHS się zmieniła, szablon odwoływałby się do plików, które nie istnieją:

{# Przed — szablon musi ręcznie pasować do konfiguracji env #}
srcset="...640w.webp 640w, ...960w.webp 960w, ..."

Poprawka: wstrzyknij szerokości wariantów jako Twig global z SiteConfigExtension, potem generuj srcset dynamicznie. Jedno źródło prawdy dla progów.

Magiczne liczby#

Response::HTTP_BAD_REQUEST zastąpiło zakodowane 400. Mała zmiana, ale spójna z zasadą: każda literalna wartość to przyszły bug, gdzie ktoś zmieni logikę ale nie liczbę.

Ekstrakcja komponentów Twig#

Między rundami jakości osobne wysiłki wyodrębniły reużywalne komponenty z monolitycznych szablonów.

Strona "O mnie"#

Strona "o mnie" była najgorszym przypadkiem — 146 linii mieszających markup profilu, karty ekspertyzy, pigułki umiejętności, projekty open source i bloki cytatów rekomendacji w jednym szablonie.

Po ekstrakcji:

{# about.html.twig — czysty i czytelny #}
{% block body %}
<article class="page-content" data-pagefind-body>
    {{ include('components/about_profile.html.twig', {
        author: site_author,
        role: 'about.role'|trans,
        headline: 'about.headline'|trans
    }) }}

    <section class="about-section">
        <h2>{{ 'about.expertise_title'|trans }}</h2>
        {{ include('components/expertise_grid.html.twig', { expertise: expertise_items }) }}
    </section>

    {{ include('components/skills_pills.html.twig', { skills: ..., labels: ... }) }}
    {{ include('components/opensource_grid.html.twig', { projects: os_projects }) }}

    {% for rec in site_author.recommendations %}
        {{ include('components/recommendation_card.html.twig', { rec: rec, ... }) }}
    {% endfor %}

    {{ include('components/about_cta.html.twig', { text: ..., url: ..., label: ... }) }}
</article>
{% endblock %}

Osiem komponentów wyodrębnionych z jednej strony: about_profile, expertise_grid, skills_pills, opensource_grid, recommendation_card, about_cta, plus error_terminal i coming_soon_terminal z innych stron.

Korzyść ze styleguide'a#

holas.pl ma dostępny tylko w dev styleguide pod /styleguide/, który pokazuje wszystkie komponenty UI. Przed ekstrakcją styleguide miał własny zakodowany markup dla każdego komponentu — który rozjeżdżał się z prawdziwymi szablonami przy zmianach.

Po ekstrakcji zarówno prawdziwa strona, jak i styleguide includują te same pliki komponentów:

{# styleguide.html.twig #}
{{ include('components/recommendation_card.html.twig', { rec: demo_recommendation, ... }) }}

{# about.html.twig #}
{{ include('components/recommendation_card.html.twig', { rec: rec, ... }) }}

Zmień komponent raz, oba się aktualizują automatycznie. Styleguide z ręcznego obciążenia synchronizacyjnego stał się bezobsługowy.

Liczba komponentów wzrosła z ~15 do 25 w ramach tych ekstrakcji.

Reorganizacja namespace'ów#

Praca nad value objects i interfejsami stworzyła wystarczająco dużo plików, że płaskie namespace'y stały się zatłoczone:

# Przed
src/Content/AdjacentPosts.php
src/Content/ArchiveMonth.php
src/Content/CategoryCount.php
src/Content/CardLayout.php
src/Service/ContentService.php
src/Service/ImageResizer.php
src/Service/DraftPreviewService.php

# Po
src/Content/ValueObject/AdjacentPosts.php
src/Content/ValueObject/ArchiveMonth.php
src/Content/ValueObject/CategoryCount.php
src/Content/Enum/CardLayout.php
src/Service/Content/ContentService.php
src/Service/Image/ImageResizer.php
src/Service/Preview/DraftPreviewService.php

CardLayout przeniesiony do Enum/ — to PHP enum z backing type dla wariantów layoutu kart wpisów:

enum CardLayout: string
{
    case Top = 'layout-top';
    case Right = 'layout-right';
    case Text = 'layout-text';
    case Left = 'layout-left';

    /** @return list<string> */
    public static function cycle(): array
    {
        return array_map(fn (self $l) => $l->value, self::cases());
    }
}

Bezpieczny typowo, z autouzupełnianiem, niemożliwy do literówki. Metoda cycle() zwraca wartości layoutów, przez które szablon listingu wpisów rotuje dla wizualnej różnorodności.

Reorganizacja dotknęła 46 plików w jednym commicie — każda instrukcja use odwołująca się do przeniesionej klasy wymagała aktualizacji. To jest dokładnie ten rodzaj mechanicznej refaktoryzacji, w którym AI błyszczy: zmień namespace, zaktualizuj wszystkie importy, zweryfikuj że nic się nie popsuło. Człowiek decyduje o docelowej strukturze; AI obsługuje żmudną część.

Workflow AI dla refaktoryzacji#

Praktyczny workflow stojący za tymi rundami:

Krok 1: Zawężony audyt. Poproś Claude Code o przegląd wszystkich plików PHP pod kątem konkretnej kategorii problemów. Nie "znajdź wszystkie problemy" — zbyt ogólne. Zamiast tego: "sprawdź każdy plik w src/ pod kątem metod zwracających tablice asocjacyjne zamiast value objects." AI czyta każdy plik i raportuje konkretne problemy ze ścieżkami plików i numerami linii.

Krok 2: Plan. Napisz plik .plans/ dokumentujący co trzeba zmienić, które pliki są dotknięte i kroki implementacji jako checkboxy. Plan jest źródłem prawdy — nie podsumowaniem intencji, ale szczegółową specyfikacją implementacji.

Krok 3: Implementacja fazami. Wykonaj jedną fazę, uruchom ddev code-check (PHP CS Fixer + PHPStan level 6), zweryfikuj że build przechodzi z ddev build. Przejdź do następnej fazy.

Krok 4: Weryfikacja. Po zakończeniu rundy uruchom pełny zestaw kontroli jakości. Liczby dla holas.pl:

$ ddev code-check
PHP CS Fixer: Found 0 of 53 files that can be fixed
PHPStan: [OK] No errors (53 files, level 6)

53 pliki PHP, zero problemów CS Fixer, zero błędów PHPStan. Automatyczne narzędzia potwierdzają to, co przegląd zamierzał.

W czym AI jest dobry przy refaktoryzacji#

• Systematyczny przegląd plik po pliku: czyta 53 pliki i raportuje każde naruszenie wzorca. Ludzie prześlizgują się; AI nie.
• Mechaniczna refaktoryzacja: zmiana nazw namespace'ów w 46 plikach, aktualizacja instrukcji import, przenoszenie stałych z klas konkretnych do interfejsów.
• Sprawdzanie spójności: weryfikacja że każdy serwis ma interfejs, każdy value object jest readonly, każde porównanie używa stylu Yoda — w całej bazie kodu.

Do czego AI potrzebuje ludzi#

• Decydowanie które abstrakcje wprowadzić: czy SidebarData powinno być jednym value object czy czterema osobnymi wartościami zwrotnymi? AI może zaimplementować jedno i drugie; człowiek decyduje co jest czystsze.
• Ocena kiedy interfejs dodaje wartość vs. obciążenie: serwis używany w jednym miejscu nie potrzebuje interfejsu dla elastyczności testowania. Zasada projektu mówi "każdy serwis dostaje interfejs" — ale to człowiek ustalił tę zasadę i człowiek może ją zmienić.
• Wiedzieć kiedy przestać: trzy rundy jakości wystarczą. Baza kodu jest czysta. Czwarta runda mikro-optymalizacji byłaby over-engineeringiem.

Pętla zwrotna AGENTS.md#

Każda runda odkrywa wzorce warte udokumentowania. Runda 1 dodała konwencję value objects do AGENTS.md. Runda 2 dodała zasadę nazewnictwa interfejsów. Runda 3 dodała zasadę "zero zakodowanych URL-i".

Następnym razem gdy Claude Code generuje nowy serwis, od razu stosuje nauki ze wszystkich trzech rund. Pierwsza wersja serwisu teraz wysyłana jest z interfejsem, używa value objects dla złożonych zwrotów i odwołuje się do nazwanych tras zamiast zakodowanych ścieżek. Iteracja kumuluje się.

Rezultat#

Po trzech rundach stan bazy kodu:

• 53 pliki PHP, wszystkie z declare(strict_types=1), jawnymi typami zwrotnymi, warunkami Yoda
• 12 interfejsów serwisów — każdy serwis wstrzykiwany przez interfejs
• 7 value objects — zero tablic asocjacyjnych dla wielopolowych zwrotów
• 1 enum — bezpieczne typowo warianty layoutu kart
• 25 komponentów Twig — reużywalne, współdzielone między stroną a styleguide'em
• 0 problemów PHP CS Fixer, 0 błędów PHPStan na poziomie 6
• 0 zakodowanych URL-i w szablonach i kontrolerach

Nic z tego nie było w pierwszej wersji. Pierwsza wersja miała wstrzyknięcia konkretnych klas, zwroty tablic, monolityczne szablony i zakodowane sprawdzenia locale. Działała — strona się budowała, strony się renderowały, użytkownicy mogli czytać posty na blogu.

Różnica to utrzymywalność. Dodanie systemu wielojęzyczności (poprzedni wpis) było proste, bo baza kodu była już czysta: interfejsy dla wszystkiego, typowane zwroty, czyste rozdzielenie odpowiedzialności. Refaktoryzacja czystej bazy kodu jest szybka. Refaktoryzacja bałaganu jest wolna i podatna na błędy.

Wyślij najpierw. Iteruj potem. Używaj AI do systematycznej pracy, którą solowy deweloper pominąłby — lub odłożył aż stanie się problemem. Trzy skupione rundy, każda budująca na poprzedniej, każda zweryfikowana automatycznymi narzędziami. Kod jest mierzalnie lepszy, a inwestycja to kilka godzin cykli przeglądów, nie tygodniowy rewrite.

Dodanie drugiego języka do strony Symfony zazwyczaj oznacza duplikowanie kontrolerów, zakodowane na sztywno prefiksy URL-i i rozsiane po całym kodzie sprawdzenia locale. holas.pl podchodzi do tego inaczej: konfiguracja locale żyje w jednym pliku YAML, trasy generowane są z własnego atrybutu PHP, a tłumaczenia łączone są przez system plików — nie przez jawne klucze.

Problem z zakodowanymi na sztywno locale#

Pierwsza działająca wersja wielojęzyczności holas.pl miała około 30 miejsc z takimi wzorcami:

#[Route('/blog/', name: 'blog_list_en')]
public function listEn(int $page = 1): Response
{
    return $this->renderList('en', $page);
}

#[Route('/pl/wpisy/', name: 'blog_list_pl')]
public function listPl(int $page = 1): Response
{
    return $this->renderList('pl', $page);
}

Każda trasa miała dwie metody — jedną na locale. Właściwa logika kontrolera żyła w prywatnej metodzie render*(); publiczne metody były czystym boilerplate'em ustawiającym locale i delegującym dalej. Siedem kontrolerów × dwa locale = 28 metod nie robiących nic pożytecznego.

Dodanie trzeciego języka wymagałoby dodania 14 kolejnych metod, plus aktualizacji szablonów, listenera locale i każdego miejsca sprawdzającego 'pl' === $locale. Kod się nie skalował.

Jedno źródło prawdy — _site.yaml#

Naprawa zaczyna się od centralizacji listy locale. Zamiast rozrzucać wiedzę o locale po plikach PHP, wszystko żyje w content/_site.yaml:

site:
  locales:
    en:
      label: "English"
      og_locale: en_US
      date_format: "M d, Y"
    pl:
      label: "Polski"
      og_locale: pl_PL
      font_preload: fonts/inter-normal-latin-ext.woff2
      date_format: "d.m.Y"

Kolejność ma znaczenie: pierwszy klucz to domyślny locale. Każdy locale niesie własne metadane — og_locale dla tagów Open Graph, date_format do renderowania szablonów, font_preload dla znaków Latin Extended, których potrzebuje tylko polski.

SiteConfigService czyta ten plik raz, cachuje go i udostępnia całej aplikacji:

interface SiteConfigServiceInterface
{
    /** @return string[] Uporządkowane kody locale, pierwszy = domyślny */
    public function getLocales(): array;

    public function getDefaultLocale(): string;

    /** @return array<string, mixed> Konfiguracja pojedynczego locale */
    public function getLocaleConfig(string $locale): array;
}

Każdy kontroler, listener i loader tras wstrzykuje ten interfejs. Żaden kod PHP nie importuje listy locale z framework.yaml ani nie koduje na sztywno ['en', 'pl'].

Własny atrybut — #[LocalizedRoute]#

Kluczową innowacją jest własny atrybut PHP, który zastępuje zduplikowane metody:

#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
final class LocalizedRoute
{
    public function __construct(
        public readonly string $name,
        public readonly string $path,
        public readonly array $requirements = [],
        public readonly array $methods = [],
        public readonly int $priority = 0,
    ) {
    }
}

Atrybut definiuje trasę tylko dla domyślnego locale. Własny LocalizedRouteLoader skanuje wszystkie kontrolery, znajduje atrybuty #[LocalizedRoute] i generuje trasy {name}_{locale} dla każdego skonfigurowanego locale:

#[LocalizedRoute('blog_list', path: '/blog/')]
#[LocalizedRoute('blog_list_paginated', path: '/blog/page/{page}/', requirements: ['page' => '\d+'])]
public function list(string $locale, int $page = 1): Response
{
    // jedna metoda obsługuje wszystkie locale
}

Ta jedna metoda zastępuje dwie listEn() / listPl() z poprzedniej wersji. Loader generuje cztery trasy z dwóch atrybutów: blog_list_en, blog_list_pl, blog_list_paginated_en, blog_list_paginated_pl.

Łącznie we wszystkich kontrolerach: 28 metod stało się 14. Każda usunięta metoda była czystym boilerplate'em.

Rozwiązywanie tras#

Loader musi wiedzieć, że /blog/ to angielska ścieżka, a /pl/wpisy/ to polska. Trzystopniowy algorytm to obsługuje:

private function resolvePath(
    string $name, string $defaultPath,
    string $locale, string $defaultLocale,
    array $overrides,
): string {
    if ($locale === $defaultLocale) {
        return $defaultPath;                          // EN: /blog/
    }

    if (isset($overrides[$name][$locale])) {
        return '/'.$locale.$overrides[$name][$locale]; // PL: /pl/wpisy/
    }

    return '/'.$locale.$defaultPath;                   // fallback: /pl/blog/
}

1. Domyślny locale — użyj path z atrybutu bez zmian: /blog/
2. Nadpisanie istnieje — dodaj /{locale} + przetłumaczoną ścieżkę z _routes.yaml
3. Brak nadpisania — dodaj /{locale} + domyślną ścieżkę: /pl/blog/

_routes.yaml — przetłumaczone segmenty ścieżek#

Tylko trasy z przetłumaczonymi segmentami URL potrzebują nadpisań. Trasy bez wpisów dostają automatyczny prefiks:

routes:
  blog_list:
    pl: /wpisy/
  blog_list_paginated:
    pl: /wpisy/strona/{page}/
  blog_category:
    pl: /wpisy/{category}/
  blog_archive:
    pl: /archiwum/{year}/{month}/
  contact:
    pl: /kontakt/
  search:
    pl: /szukaj/

blog_tag nie ma wpisu, więc blog_tag_pl dostaje automatyczny prefiks: /pl/tag/{tag}/. Dodanie niemieckiego wymagałoby dodania wpisów de: do tras wymagających tłumaczenia i niczego dla tras, gdzie angielska ścieżka jest odpowiednia.

Dwa wzorce rozwiązywania URL-i#

Szablony muszą linkować do stron. Są dwa fundamentalnie różne przypadki:

Trasy strukturalne pochodzą z routera — generowane przez LocalizedRouteLoader i mają nazwy {name}_{locale}. URL-e treści pochodzą z pól slug we frontmatter — każdy en.md i pl.md definiuje własny URL.

{# Strukturalne: router zna ścieżkę #}
<a href="{{ path('blog_list_' ~ locale) }}">Blog</a>
<a href="{{ path('contact_' ~ locale) }}">Kontakt</a>

{# Treść: wyszukaj po kluczu katalogu #}
<a href="{{ content_url('about', locale) }}">O mnie</a>
<a href="{{ content_url('privacy-policy', locale) }}">Prywatność</a>

content_url() to własna funkcja Twig, która wyszukuje ContentItem po jego kluczu katalogu — nazwie folderu — i zwraca URL z frontmatter. Zastępuje to stare podejście z zakodowanymi na sztywno slugami per locale w szablonach.

Współlokalizowana treść — system plików jako łącznik tłumaczeń#

Pliki treści tego samego wpisu żyją w tym samym katalogu:

content/blog/tutorials/my-post/
    en.md  → slug: "blog/my-post"
    pl.md  → slug: "pl/blog/moj-wpis"
    files/ → obrazy serwowane pod /media/my-post/

Oba pliki w tym samym folderze są automatycznie łączone jako tłumaczenia. Nie potrzeba jawnego pola translation_key. ContentItem::directoryKey() zwraca nazwę folderu ("my-post"), a TranslationMapBuilder używa jej do budowy tablicy wyszukiwania:

public function build(array $trees): array
{
    $map = [];

    foreach ($trees as $locale => $tree) {
        foreach ($tree->getAllItems() as $item) {
            $key = $item->directoryKey();
            if (null === $key || '' === $item->url()) {
                continue;
            }
            $map[$key][$locale] = $item->url();
        }
    }

    return $map;
}

Wynik: $map['my-post']['en'] = '/blog/my-post/', $map['my-post']['pl'] = '/pl/blog/moj-wpis/'. Ta mapa napędza tagi hreflang <link> w nagłówku HTML i przełącznik języka.

Nie każdy wpis potrzebuje obu plików locale. Wpis z samym en.md nie pojawi się na polskich listingach, a przełącznik języka przekieruje na stronę główną drugiego języka.

Przełącznik języka — łańcuch fallbacków#

Przełącznik języka wydaje się prosty — link do tej samej strony w innym języku. W praktyce musi obsługiwać częściowe tłumaczenia, strony tagów, strony archiwum i paginowane listingi. Łańcuch fallbacków:

{# 1. Spróbuj mapy tłumaczeń (strona istnieje w innym locale) #}
{% if tk and translation_map[tk][other] is defined %}
    {% set url = translation_map[tk][other] %}
{% endif %}

{# 2. Spróbuj URL podany przez kontroler (strony tagów) #}
{% if url is null and lang_switch_url is defined %}
    {% set url = lang_switch_url %}
{% endif %}

{# 3. Fallback: archiwum, paginowany listing lub strona główna #}
{% if url is null %}
    {% if filter_type is same as('archive') and archive_year is defined %}
        {% set url = path('blog_archive_' ~ other, {year: ..., month: ...}) %}
    {% elseif current_page > 1 %}
        {% set url = path('blog_list_paginated_' ~ other, {page: current_page}) %}
    {% else %}
        {% set url = path('home_' ~ other) %}
    {% endif %}
{% endif %}

Strony tagów wymagają specjalnej obsługi: BlogController tłumaczy slug tagu między locale (np. security → bezpieczenstwo) i sprawdza, czy drugi locale ma jakieś wpisy z tym tagiem. Jeśli tak, przełącznik linkuje do przetłumaczonej strony tagu. Jeśli nie, wraca do listingu wpisów drugiego locale.

Po stronie klienta locale-redirect.js obsługuje detekcję języka przy pierwszej wizycie. Czyta navigator.language, porównuje z listą skonfigurowanych locale (z atrybutu data-locales na <html>) i zapisuje preferencje w ciasteczku. Przy kolejnych wizytach przekierowuje do zapisanej preferencji. Lista locale nie jest zakodowana na sztywno w JavaScript — pochodzi z tej samej konfiguracji _site.yaml, przekazanej przez Twig.

Detekcja locale#

LocaleListener działa z priorytetem 8 — po wbudowanych listenerach locale Symfony — i wykrywa locale ze ścieżki URL:

private function detectLocale(string $path): string
{
    $defaultLocale = $this->siteConfig->getDefaultLocale();

    foreach ($this->siteConfig->getLocales() as $locale) {
        if ($locale === $defaultLocale) {
            continue;
        }

        if (str_starts_with($path, '/'.$locale.'/') || '/'.$locale === $path) {
            return $locale;
        }
    }

    return $defaultLocale;
}

Żadnego zakodowanego sprawdzenia /pl/. Iteruje skonfigurowane locale dynamicznie. Dodanie nowego locale do _site.yaml wystarczy, aby listener zaczął go wykrywać.

Dodanie nowego języka — zero zmian w PHP#

To jest efekt końcowy. Dodanie niemieckiego do holas.pl wymaga:

1. content/_site.yaml — dodaj wpis de: z label, og_locale, date_format
2. content/_routes.yaml — dodaj nadpisania de: dla przetłumaczonych segmentów tras
3. translations/messages.de.yaml — niemieckie stringi UI (etykiety nawigacji, tekst przycisków itp.)
4. content/_tags.yaml — niemieckie tłumaczenia tagów
5. Pliki treści — utwórz de.md obok en.md i pl.md dla wpisów, które powinny istnieć po niemiecku

Zero zmienionych plików PHP. Zero edytowanych szablonów Twig. Zero dodanych metod kontrolera. Loader tras generuje niemieckie trasy automatycznie. Listener locale wykrywa ścieżki /de/. Przełącznik języka renderuje dropdown zamiast pojedynczego linka. Mapa tłumaczeń zawiera niemieckie URL-e.

28 metod kontrolera specyficznych per locale i 30 zakodowanych na sztywno sprawdzeń locale z pierwszej wersji wymagałoby edycji ponad 20 plików, aby dodać niemiecki. Podejście oparte na konfiguracji oznacza edycję 5 plików konfiguracyjnych i tworzenie treści.

Decyzje architektoniczne, które to umożliwiają — SiteConfigService jako jedyne źródło prawdy o locale, LocalizedRouteLoader generujący trasy z atrybutów, współlokalizowana treść jako łącznik tłumaczeń — to decyzje, które wyglądają na over-engineering, gdy masz tylko dwa języki. Nie są. To różnica między "dodanie języka to tydzień pracy" a "dodanie języka to popołudnie z konfiguracją."

Następny wpis opisuje jak baza kodu poprawiała się przez iteracyjne rundy jakości — value objects, interfejsy, ekstrakcja komponentów — z AI obsługującym systematyczną pracę przeglądową.

Na statycznej stronie nie ma serwera obsługującego żądania ani warstwy aplikacyjnej sprawdzającej czas. Obie funkcje wymagają celowej implementacji — a właściwym miejscem dla obu jest krok budowania.

Responsywne obrazy#

Problem#

Wyróżnione obrazy na holas.pl mają rozmiar 1280×720px w formacie WebP. Na przeglądarce desktopowej to właściwy rozmiar. Na ekranie mobilnym o szerokości 400px przeglądarka pobiera obraz o szerokości 1280 pikseli, aby wyświetlić go na 400 pikselach — to mniej więcej 10-krotność potrzebnych danych.

Rozwiązaniem jest srcset + sizes: poinformuj przeglądarkę o dostępnych wariantach obrazu i o tym, jak duży jest obraz przy każdej szerokości widoku, a następnie pozwól jej wybrać właściwy plik. Ograniczenie statycznej strony: każdy wariant musi istnieć jako plik zanim nadejdzie jakiekolwiek żądanie. Nie ma skalowania na żądanie.

Generowanie wariantów w czasie budowania#

BuildStaticSiteCommand generuje warianty po skopiowaniu plików multimedialnych do public/static/media/. Skanuje pliki .webp, odczytuje faktyczne wymiary każdego pliku za pomocą getimagesize() i generuje warianty przez ImageResizerInterface::resize():

$variantWidths = $this->responsiveImageService->getVariantWidths($width);

foreach ($variantWidths as $variantWidth) {
    $this->imageResizer->resize(
        $filePath,
        $dir . '/' . $baseName . '-' . $variantWidth . 'w.webp',
        $variantWidth,
    );
}

ImageResizer::resize() wywołuje ImageMagick:

magick source.webp -resize 640x -quality 82 -strip -define webp:method=6 source-640w.webp

-resize 640x skaluje do 640px szerokości, zachowując proporcje. -quality 82 -strip -define webp:method=6 odpowiada ustawieniom produkcyjnym obrazów i usuwa dane EXIF.

Nazwy wariantów są konwencjonalne: obraz.webp → obraz-640w.webp, obraz-960w.webp. Budowanie pomija pliki kończące się na -640w lub -960w, aby uniknąć ponownego przetwarzania wcześniej wygenerowanych wariantów.

ResponsiveImageService#

Dwa miejsca muszą wiedzieć, które warianty istnieją: BuildStaticSiteCommand (które pliki generować) i SrcsetExtension (które nazwy plików referencjonować w HTML). Zamiast duplikować logikę progów, oba wstrzykują ResponsiveImageServiceInterface:

interface ResponsiveImageServiceInterface
{
    /** @return int[] */
    public function getVariantWidths(int $sourceWidth): array;

    public function buildSrcset(string $src, int $sourceWidth): string;
}

Implementacja:

public function getVariantWidths(int $sourceWidth): array
{
    if (960 < $sourceWidth) {
        return [640, 960];
    }
    if (640 < $sourceWidth) {
        return [640];
    }

    return [];
}

public function buildSrcset(string $src, int $sourceWidth): string
{
    $base = substr($src, 0, -5);  // usuń .webp

    if (960 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s-960w.webp 960w, %s 1280w', $base, $base, $src);
    }
    if (640 < $sourceWidth) {
        return sprintf('%s-640w.webp 640w, %s 960w', $base, $src);
    }

    return '';
}

Obrazy o szerokości ≤640px nie mają wariantów — oryginał jest już wystarczająco mały. buildSrcset() zwraca '' sygnalizując, że atrybut srcset nie jest potrzebny.

Jeśli kiedykolwiek zajdzie potrzeba zmiany progów, jest jedno miejsce do aktualizacji.

Komponent wyróżnionego obrazu#

Komponent responsive_img.html.twig renderuje wyróżnione obrazy z srcset zakodowanym na stałe dla progów 640/960/1280:

<img src="{{ src }}"
     srcset="{{ src|replace({'.webp': '-640w.webp'}) }} 640w,
             {{ src|replace({'.webp': '-960w.webp'}) }} 960w,
             {{ src }} 1280w"
     sizes="{{ sizes|default('(max-width: 48em) 100vw, 720px') }}"
     alt="{{ alt }}"
     width="{{ width|default(1280) }}"
     height="{{ height|default(720) }}">

sizes="(max-width: 48em) 100vw, 720px" mówi przeglądarce: poniżej szerokości widoku 48em obraz wypełnia cały widok; powyżej jest ograniczony do 720px (szerokość kolumny treści). Przeglądarka używa tego do wyboru właściwego wariantu przed pobraniem czegokolwiek.

width i height są jawne w celu zapobiegania Cumulative Layout Shift — przeglądarka rezerwuje dokładną przestrzeń dla obrazu przed jego załadowaniem. Bez nich układ przesuwa się gdy obraz przybywa.

Obrazy inline w treści#

Obrazy Markdown w treści wpisu renderują się jako zwykłe tagi <img> bez srcset. Wpis z diagramem lub zrzutem ekranu pod adresem /media/post-dir/diagram.webp serwowałby pełnowymiarowy obraz również na urządzeniach mobilnych.

Filtr Twig srcset_media rozwiązuje ten problem. W post.html.twig:

{{ content.htmlContent|srcset_media|raw }}

SrcsetExtension::srcsetMedia() znajduje wszystkie tagi <img> z /media/*.webp za pomocą wyrażenia regularnego, odczytuje szerokość źródłowego obrazu z katalogu content/ (nie ze statycznego wyjścia) i wstrzykuje srcset i sizes:

$result = preg_replace_callback(
    '/<img(\s[^>]*)src="(\/media\/[^"]+\.webp)"([^>]*)>/i',
    function (array $matches): string {
        $src = $matches[2];

        // pomiń jeśli srcset już jest obecny
        if (str_contains($matches[1], 'srcset') || str_contains($matches[3], 'srcset')) {
            return $matches[0];
        }

        $width = $this->getSourceWidth($src);
        if (null === $width) {
            return $matches[0];
        }

        $srcset = $this->responsiveImageService->buildSrcset($src, $width);
        if ('' === $srcset) {
            return $matches[0];  // brak wariantów — zostaw bez zmian
        }

        return sprintf(
            '<img%ssrc="%s" srcset="%s" sizes="(max-width: 48em) 100vw, 720px"%s>',
            $matches[1], $src, $srcset, $matches[3],
        );
    },
    $html,
);

getSourceWidth() wyszukuje faktyczny plik źródłowy w content/ (nie w public/static/), ponieważ tam żyją oryginalne wymiary. Obrazy bez wariantów — małe zrzuty ekranu inline o szerokości ≤640px — pozostają niezmienione.

Zaplanowane wpisy#

Problem#

Wpis z date: 2026-06-01 nie powinien pojawiać się na listingach do 1 czerwca. Strona przebudowuje się każdej nocy, więc wpis z przyszłą datą po prostu nie pojawi się w ContentTree::getAllPosts() aż do budowania po dacie publikacji. Ta część działa automatycznie.

URL to inny problem. Jeśli ktoś udostępni link do wpisu przed jego opublikowaniem, dostanie błąd 404. Lepiej serwować stronę "coming soon" pod dokładnym URL-em, który wpis zajmie.

ContentItem::isScheduled()#

public function isScheduled(): bool
{
    $date = $this->date();

    return null !== $date && $date > new \DateTimeImmutable();
}

Jedno porównanie. isDraft() ma pierwszeństwo — wpis z jednoczesnym draft: true i przyszłą datą jest traktowany jako szkic i wykluczony ze wszystkich budowań.

Krok budowania: strony coming soon#

BuildStaticSiteCommand::collectRoutes() zbiera dwie kategorie URL-i wpisów:

• Opublikowane wpisy przez ContentTree::getAllPosts() — renderowane pełnym szablonem wpisu
• Zaplanowane wpisy przez ContentTree::getScheduledPosts() — renderowane szablonem coming soon

Oba produkują statyczne pliki HTML pod swoim docelowym URL-em. Gdy data wpisu minie i nastąpi kolejne budowanie, isScheduled() zwraca false, URL przechodzi na listę opublikowanych, a pełny HTML wpisu zastępuje HTML coming soon. Nie potrzeba przekierowania ani specjalnej obsługi.

Strona coming soon#

Szablon coming soon używa tej samej estetyki zielonego terminalu co strony błędów:

{% block robots %}<meta name="robots" content="noindex, nofollow">{% endblock %}

<pre class="coming-soon-terminal"><code>
<span class="coming-soon-terminal__code">COMING_SOON</span>
{% if days_until <= 14 %}
<span class="coming-soon-terminal__text">{{ post.title }}</span>
<span class="coming-soon-terminal__date">Publikacja: {{ post.date|date('Y-m-d') }}</span>
{% endif %}
</code></pre>

noindex, nofollow — strona obsługuje bezpośrednie linki bez indeksowania i bez przekazywania link equity.

Jeśli data publikacji jest ≤14 dni, tytuł i data są pokazane. Dalej: tylko kod COMING_SOON, bez daty. Próg 14 dni unika publicznego zobowiązania do konkretnej daty, która mogłaby się opóźnić.

Pasek narzędzi podglądu w trybie dev#

W produkcji zaplanowane wpisy są niewidoczne — pojawiają się tylko jako strony coming soon pod swoimi URL-ami, nie na żadnym listingu.

W trybie deweloperskim piszesz treść zaplanowanego wpisu i potrzebujesz ją widzieć. Pasek narzędzi profilera Symfony dostaje przełącznik z ikoną kalendarza ("Podgląd zaplanowanych"). Gdy jest włączony, zaplanowane wpisy pojawiają się na listingach z plakietką [PLANNED]:

{% if post.isDraft() %}
    <span class="post-card-badge post-card-badge--draft">[DRAFT]</span>
{% elseif post.isScheduled() %}
    <span class="post-card-badge post-card-badge--planned">[PLANNED]</span>
{% else %}
    {# plakietki: przypięty / nowy / niedawno zaktualizowany #}
{% endif %}

Wyłącz go, aby podejrzeć jak będzie wyglądać produkcja. Mechanizm jest lustrzanym odbiciem istniejącego przełącznika podglądu szkiców — ten sam wzorzec klucza sesji (scheduled_preview), ta sama struktura kontrolera.

Wzorzec kroku budowania#

Obie funkcje podążają tym samym podejściem: przenieś pracę do kroku budowania, utrzymaj prostą warstwę serwowania.

Responsywne obrazy: generuj wszystkie warianty w czasie budowania. Kilka sekund wywołań ImageMagick podczas ddev build oszczędza przepustowość przy każdym mobilnym ładowaniu strony przez cały okres życia wpisu.

Zaplanowane wpisy: wstępnie renderuj strony coming soon zamiast obsługiwać "jeszcze nieopublikowany" w czasie żądania. Statyczny plik istnieje, nginx go serwuje, PHP nie jest zaangażowany.

Budowanie wykonuje się raz. nginx serwuje wynik każdemu odwiedzającemu. Każda praca, która może się przenieść do kroku budowania, to praca, której serwer nie musi wykonywać.

Potok budowania, który to umożliwia, opisany jest w części 2 tej serii. Dwukonteinerowe środowisko produkcyjne, które go uruchamia, opisane jest w części 3.

Czego Lighthouse SEO nie sprawdza: czy dane strukturalne są kompletne, jak strona renderuje się jako karta społecznościowa, co widzą czytniki RSS, czy Google może znaleźć i zaindeksować obrazy bez crawlowania każdej podstrony.

Ten wpis opisuje warstwę implementacyjną pod tym wynikiem.

Dane strukturalne#

Dane strukturalne to JSON-LD w bloku <script type="application/ld+json">. Mówią wyszukiwarkom, czym jest strona — nie tylko co mówi. holas.pl używa czterech typów schematu.

WebSite + SearchAction#

Każda strona zawiera schemat WebSite identyfikujący witrynę i jej punkt wyszukiwania:

{
    "@context": "https://schema.org",
    "@type": "WebSite",
    "name": "holas.pl",
    "url": "https://holas.pl",
    "author": {
        "@type": "Person",
        "name": "Paweł Holik",
        "url": "https://holas.pl"
    },
    "potentialAction": {
        "@type": "SearchAction",
        "target": {
            "@type": "EntryPoint",
            "urlTemplate": "https://holas.pl/search/?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
    }
}

potentialAction umożliwia pole wyszukiwania w wynikach Google — pole wyszukiwania widoczne bezpośrednio w wynikach Google dla witryny. Kieruje do wyszukiwania opartego na Pagefind pod adresem /search/. To jedno dodatkowe pole w istniejącym schemacie bez żadnych wad.

BlogPosting#

Wpisy na blogu mają najbogatszy schemat. Poza headline, description, url i datePublished, kilka pól wpływa na to, jak Google reprezentuje treść:

• inLanguage — "en" lub "pl", wymagane do indeksowania wielojęzycznego
• wordCount — obliczany w czasie parsowania przez ContentItem::wordCount() (usuwa tagi HTML, liczy tokeny)
• articleSection — kategoria wpisu
• keywords — tagi wpisu jako ciąg rozdzielony przecinkami
• image — zagnieżdżony ImageObject z url, width i height

{
    "@type": "BlogPosting",
    "headline": "Tytuł wpisu",
    "inLanguage": "pl",
    "wordCount": 842,
    "articleSection": "porady",
    "keywords": "seo, symfony, statyczna-strona",
    "image": {
        "@type": "ImageObject",
        "url": "https://holas.pl/media/post-dir/featured.webp",
        "width": 1280,
        "height": 720
    }
}

Bez ImageObject Google traktuje wyróżniony obraz jako nieznany załącznik. Z jawnie podanymi szerokością i wysokością obraz kwalifikuje się do dużych kart podglądu w Google Discover i Search.

BreadcrumbList#

Google może zastąpić surowy URL w wynikach wyszukiwania nawigacją okruszkową — "Strona główna / Blog / porady / Tytuł wpisu". Wymaga to schematu BreadcrumbList.

Jest renderowany w breadcrumb.html.twig obok nawigacji HTML. Każdy okruszek to ListItem z position i item (URL). Ostatni element — bieżąca strona — ma nazwę, ale bez URL:

{
    "@type": "BreadcrumbList",
    "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Strona główna", "item": "https://holas.pl/pl/" },
        { "@type": "ListItem", "position": 2, "name": "Wpisy", "item": "https://holas.pl/pl/wpisy/" },
        { "@type": "ListItem", "position": 3, "name": "porady", "item": "https://holas.pl/pl/wpisy/porady/" },
        { "@type": "ListItem", "position": 4, "name": "Tytuł wpisu" }
    ]
}

CollectionPage + ItemList#

Strony z listingami kategorii, tagów i archiwum zawierają CollectionPage z zagnieżdżonym ItemList. Każdy wpis ma position i url. Renderowany tylko gdy listing zawiera wpisy — pusta strona kategorii tego nie dostaje.

{
    "@type": "CollectionPage",
    "name": "porady | holas.pl",
    "mainEntity": {
        "@type": "ItemList",
        "numberOfItems": 5,
        "itemListElement": [
            { "@type": "ListItem", "position": 1, "url": "https://holas.pl/pl/wpis/" }
        ]
    }
}

Udostępnianie w mediach społecznościowych#

Wymiary obrazu OpenGraph#

Bez og:image:width i og:image:height platformy jak LinkedIn i Slack muszą pobrać obraz zanim wyrenderują kartę podglądu. Z nimi karta renderuje się natychmiast:

<!-- wpis na blogu (WebP, 1280×720) -->
<meta property="og:image:width" content="1280">
<meta property="og:image:height" content="720">
<meta property="og:image:type" content="image/webp">

<!-- inne strony (domyślny og:image, JPG, 1200×630) -->
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/jpeg">

Warunek jest w base.html.twig: jeśli obiekt content z obrazem jest zdefiniowany (wpis lub strona z wyróżnionym obrazem), użyj wymiarów WebP; w przeciwnym razie użyj wartości domyślnych dla og-default.jpg. Wyjątek dla JPG istnieje dlatego, że og:image jest odczytywany przez zewnętrzne crawlery, które nie obsługują WebP niezawodnie.

Karta Twitter/X#

Podstawowy typ twitter:card był już obecny. Dodano trzy jawne pola:

<meta name="twitter:title" content="...">
<meta name="twitter:description" content="...">
<meta name="twitter:image" content="...">

Bez nich Twitter/X wraca do właściwości OG. Jawne meta usuwa tę zależność — jeśli przetwarzanie OG ma jakikolwiek problem, Twitter Card nadal ma poprawne wartości.

Meta article:*#

Wpisy na blogu dostają specyficzne dla artykułu meta OG w bloku og_article_meta szablonu post.html.twig:

<meta property="article:published_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:modified_time" content="2026-06-21T00:00:00+00:00">
<meta property="article:author" content="Paweł Holik">
<meta property="article:section" content="porady">
<meta property="article:tag" content="seo">
<meta property="article:tag" content="symfony">
<meta property="article:tag" content="statyczna-strona">

article:tag to jeden element na tag — nie oddzielony przecinkami ciąg. Specyfikacja Open Graph wymaga osobnych elementów dla właściwości wielowartościowych.

Czytniki RSS#

content:encoded#

Domyślny <description> RSS zawiera tylko fragment wpisu — pierwszy akapit z usuniętym HTML. content:encoded przenosi pełny HTML wpisu w bloku CDATA:

<content:encoded><![CDATA[<p>Pełna treść wpisu...</p>]]></content:encoded>

Wymaga to xmlns:content="http://purl.org/rss/1.0/modules/content/" na elemencie głównym <rss>. Czytniki RSS jak NetNewsWire, Reeder i Feedbin renderują content:encoded inline — subskrybenci czytają pełny artykuł bez opuszczania czytnika.

category i media:content#

Każdy element RSS dostaje elementy <category> dla kategorii wpisu i każdego tagu:

<category>porady</category>
<category>seo</category>
<category>symfony</category>

media:content dołącza wyróżniony obraz jako typowany załącznik multimedialny:

<media:content url="https://holas.pl/media/post-dir/featured.webp"
               medium="image" type="image/webp" width="1280" height="720"/>

Czytniki RSS renderujące obrazy inline (Feedly, Inoreader) używają tego do miniatury wpisu na liście. Wymaga to xmlns:media="http://search.yahoo.com/mrss/" na elemencie <rss>.

Sygnały dla crawlerów#

max-image-preview:large#

Domyślne zachowanie robots ogranicza podglądy obrazów w Google Search i Discover do standardowego rozmiaru. max-image-preview:large włącza podglądy pełnowymiarowe. W połączeniu z max-snippet:-1 (bez ograniczenia długości fragmentu tekstu) jest to domyślny robots meta na każdej stronie:

<meta name="robots" content="max-image-preview:large, max-snippet:-1">

Zaimplementowane jako domyślny {% block robots %} w base.html.twig. Szablony potomne nadpisują blok dla stron, które nie powinny być indeksowane — strony "coming soon" używają noindex, nofollow, strona wyszukiwania używa noindex.

Sitemap obrazów#

Standardowy sitemap wyświetla URL stron. Sitemap obrazów dodaje bloki <image:image>, dając Google bezpośredni wgląd w lokalizacje obrazów i ich teksty alternatywne bez crawlowania każdej strony:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
    <url>
        <loc>https://holas.pl/wpis/</loc>
        <image:image>
            <image:loc>https://holas.pl/media/post-name/featured.webp</image:loc>
            <image:title>Tekst alternatywny z frontmatter image_alt</image:title>
        </image:image>
    </url>

image:title pochodzi z pola frontmatter image_alt — tego samego tekstu, który jest używany w atrybucie HTML alt. Zarówno przestrzeń nazw xmlns:image, jak i blok image:image są w sitemap.xml.twig.

Co się zmieniło#

Wynik Lighthouse SEO był 100 przed tymi zmianami. Po nich nadal jest 100. Ten wynik mierzy techniczne minimum: indeksowalność, tagi meta, responsywność mobilną.

Powyższe zmiany działają na innym poziomie. Dane strukturalne kształtują sposób reprezentowania treści przez wyszukiwarki w bogatych wynikach. Jawne meta społecznościowe zapewniają poprawne renderowanie bez polegania na logice fallback platformy. Rozszerzenia RSS pozwalają subskrybentom czytać pełne wpisy w swoim czytniku. Sitemap obrazów daje Google widoczność obrazów bez potrzeby crawlowania każdej strony.

Żadna z tych zmian nie jest architektonicznie złożona — większość to uzupełnienia szablonów Twig i deklaracje przestrzeni nazw. Ograniczeniem jest dyscyplina: każde pole wymaga rzeczywistej wartości z frontmatter, nie zastępnika.

Architektura, która sprawia, że to wszystko jest proste, opisana jest w części 2 tej serii — potok generowania statycznego, który produkuje kompletny HTML dla każdej strony.

Ten wpis omawia, co konkretnie napędza każdy wynik. Większość z tego nie jest wynikiem optymalizacji — to efekt uboczny sposobu, w jaki strona jest zbudowana.

Performance#

Główny powód, dla którego wynik performance wynosi 100, jest taki, że nginx serwuje wstępnie wyrenderowane pliki HTML bez udziału PHP. Nie ma zapytania do bazy danych, renderowania szablonów ani bootstrapowania frameworka przy każdym żądaniu. Plik trafia z dysku do klienta. Raspberry Pi 5 obsługuje to bez najmniejszego wysiłku.

Reszta wynika z tego bezpośrednio:

Zasoby są hashowane i niezmienne. Pliki JavaScript i CSS skompilowane przez Symfony AssetMapper otrzymują hash zawartości w nazwie pliku (app-a1b2c3d4.css). nginx serwuje je z nagłówkiem Cache-Control: public, max-age=31536000, immutable — rok czasu, bez rewalidacji. Przy ponownych odwiedzinach przeglądarka obsługuje wszystko z cache. Przy deploymencie hash się zmienia i nowy plik jest pobierany.

JavaScript jest minimalny i nie blokuje renderowania. Strona używa natywnych modułów ES przez importmap — bez bundlera, bez webpacka, bez jQuery. Jest siedem małych plików JS: app.js, contact.js, cookie-banner.js, lightbox.js, locale-redirect.js, nav-toggle.js, tagline.js. Żaden z nich nie blokuje renderowania. Wyszukiwanie obsługuje Pagefind — statyczny indeks wyszukiwania oparty na WebAssembly, który ładuje się leniwie — tylko na stronie wyszukiwania, tylko gdy jest potrzebny.

Obrazy są w formacie WebP. Zdjęcia wyróżniające są zapisane jako WebP o wymiarach 1280×720. Żadnych dużych nieskompresowanych JPEGów.

Brak zasobów blokujących renderowanie. Nie ma <link rel="stylesheet"> do zewnętrznego CDN z fontami ani synchronicznego skryptu third-party ładowanego w <head>. CSS jest kompilowany lokalnie i serwowany jako hashowany zasób.

Accessibility#

<html lang> ustawiany na podstawie locale. Każda strona ma poprawny atrybut języka — lang="en" dla stron angielskich, lang="pl" dla polskich. Jest ustawiany w bazowym szablonie Twig na podstawie aktualnego locale, nie na sztywno.

Semantyczny HTML w całości. Layout używa <nav>, <main>, <article>, <aside>, <footer> — nie sekwencji elementów <div>. Nagłówki zachowują logiczną hierarchię: jeden <h1> na stronę, <h2> dla sekcji najwyższego poziomu, <h3> poniżej.

Kontrast kolorów jest zachowany. Strona używa ciemnej palety opartej na Monokai: tekst #F8F8F2 na tle #242424. To współczynnik kontrastu 15,5:1, znacznie powyżej progu WCAG AA wynoszącego 4,5:1.

Wszystkie obrazy mają atrybuty alt. Jest to wymuszane w szablonach Twig — tag <img> zawsze wyprowadza tekst alt z frontmatter elementu treści.

Metatag viewport jest obecny. Każda strona zawiera <meta name="viewport" content="width=device-width, initial-scale=1">.

Best Practices#

HTTPS. Strona działa za Cloudflare, który obsługuje zakończenie TLS. Wszystkie żądania HTTP są przekierowywane na HTTPS.

Nagłówki bezpieczeństwa. nginx ustawia pełny zestaw na każdej odpowiedzi:

add_header X-Frame-Options           "SAMEORIGIN"                       always;
add_header X-Content-Type-Options    "nosniff"                          always;
add_header Referrer-Policy           "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy        "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy   "default-src 'self'; ..." always;

CSP wymagał pewnej uwagi — wasm-unsafe-eval dla paczki WASM Pagefinda oraz challenges.cloudflare.com jako dozwolone źródło ramki dla CAPTCHA Turnstile w formularzu kontaktowym. Wszystko inne to 'self'.

Brak przestarzałych API. Strona nie używa document.write, XMLHttpRequest, layoutów <table> ani niczego innego, co Lighthouse oznacza jako przestarzałą praktykę.

Brak mixed content. Każdy zewnętrzny zasób (skrypt Cloudflare Turnstile) jest ładowany przez HTTPS.

SEO#

Wstępnie wyrenderowany HTML. Roboty wyszukiwarek otrzymują kompletny HTML — każdy nagłówek, akapit, blok kodu i link jest w źródle strony. Nie ma renderowania po stronie klienta, na które trzeba czekać, nie potrzeba JavaScript, żeby zobaczyć treść.

Sitemap z hreflang. Mapa strony pod adresem /sitemap.xml wyświetla wszystkie wpisy i strony dla obu wersji językowych. Każdy wpis zawiera pary <xhtml:link rel="alternate" hreflang="..."> wskazujące na wersje EN i PL. Jeśli wpis istnieje tylko w jednym języku, wpis alternatywny jest pomijany.

hreflang w <head>. Każda strona zawiera tagi <link rel="alternate" hreflang="..."> dla obu locale. Przełącznik języka używa tej samej mapy tłumaczeń — zbudowanej z współlokalizowanych plików en.md/pl.md w każdym katalogu wpisu.

Kanoniczne URL-e. Każda strona zawiera <link rel="canonical" href="..."> wskazujący na autorytatywny URL tej strony.

Metadane OpenGraph. Każda strona ma og:title, og:description, og:image i og:url. Są wypełniane z frontmatter — pola title, description i image mapują się bezpośrednio na tagi OG w bazowym szablonie.

Opisowe tytuły i meta opisy. Pola frontmatter title i description są wymagane. Strona nie ma żadnych stron z domyślnymi lub brakującymi meta opisami.

Co nie było automatyczne#

Większość z powyższego wynika z architektury — pliki statyczne, minimalny JS, wstępnie wyrenderowany HTML. Ale kilka rzeczy wymagało świadomej pracy.

Atrybuty dostępności. Atrybut lang, wymuszanie tekstu alt, hierarchia nagłówków i wybór semantycznych elementów — wszystko to musiało zostać zapisane w szablonach. Nie pojawia się samo z siebie.

CSP. Prawidłowe skonfigurowanie Content-Security-Policy wymagało kilku iteracji. Pagefind używa WebAssembly, co wymaga wasm-unsafe-eval. Cloudflare Turnstile ładuje się z challenges.cloudflare.com i potrzebuje wyjątku frame-src. Każdy zewnętrzny zasób wymaga jawnego wyjątku w CSP — dodanie jednego bez sprawdzenia psuje wynik.

hreflang. Serwis TranslationMapBuilder buduje mapę {directoryKey → {locale → url}} ze współlokalizowanych plików treści. Jeśli wpis istnieje tylko w jednym locale, wpis hreflang dla brakującego locale jest pomijany zamiast wskazywać na nieistniejący URL. Wymagało to celowego fallbacku w szablonie, nie tylko pętli po wszystkich locale.

Wynik#

Cztery setki to nie efekt sprintu optymalizacyjnego. To to, co dostaje się, gdy strona serwuje pliki statyczne, używa minimalnego JavaScript, ma właściwą strukturę HTML i ustawia nagłówki bezpieczeństwa, które powinny być na każdej stronie produkcyjnej.

Architektura jest szczegółowo opisana w części 2 tej serii (jak Symfony generuje statyczny HTML) i części 4 (jak nginx serwuje go na produkcji).

notACMS wyrósł z mojej własnej strony i przez pierwsze wydanie był jednym kawałkiem: klonujesz repo, masz gotowy design, zaczynasz od nadpisywania. Działało, ale każdy kto chciał zbudować własny wygląd od zera musiał walczyć z rzeczami których nie potrzebował. 1.1.0 rozwiązuje to przez podział na rdzeń i motyw demo.

Rdzeń jest skeletonem#

templates/, assets/, translations/ to teraz minimalny szkielet. Systemowe fonty, tryb jasny, około 200 linii CSS. Wszystkie funkcje działają — blog, strony, wyszukiwarka, RSS, mapa strony, responsywne obrazki, formularz kontaktowy — ale wygląda to jak strona z lat 90. Celowo. Jeśli budujesz własny design, nie musisz walczyć z motywem który narzuca ci język wizualny.

Motyw demo mieszka w docs/demo/ i jest domyślnym seedem — ./notACMS deploy albo ddev build położą go przy pierwszym uruchomieniu. Jeśli wolisz skeleton, dodaj --bare:

./notACMS deploy           # amber-phosphor (domyślnie), gotowy do poprawiania
./notACMS deploy --bare    # skeleton, budujesz od zera

Cała reszta — wzorzec lokalnych nadpisań przez katalog local/, brak edycji rdzenia, czysty git pull — działa tak samo niezależnie od wyboru.

Co jeszcze trafiło do 1.1.0#

Czas czytania i pasek postępu na postach i dokumentach. Przełącznik języków jako rozszerzenie Twig. Fragmenty postów które nie przeciekają już # z anchorów nagłówków. Szkielet testów PHPUnit w tests/. Skille AI-agent do pracy z repozytorium. Pakiet zgodności starego motywu w docs/customization/old-template/ — jedno cp -r i wracasz do wyglądu z 1.0.0.

1.1.1 — łatka którą wymusiło realne użycie#

Przygotowując ten wpis na holas.pl, deployując na produkcję, zauważyłem coś irytującego: ./notACMS deploy --prod przy każdym uruchomieniu robił backup local/ i podmieniał go świeżą kopią. Jeśli miałeś tam już treść, znikała. Deploy nie odróżniał "użytkownik chce zastąpić cały motyw" od "użytkownik chce tylko zbudować stronę z istniejącą treścią".

1.1.1 naprawia to tak, że deploy działa jak ddev build: inicjuje local/ tylko gdy katalog nie istnieje lub jest pusty. Treść którą już masz zostaje nienaruszona. Chcesz wymusić reseed? Podaj --bare lub --demo jawnie.

Drugą zmianą są etykiety nawigacji z frontmatteru. Do tej pory każda zakładka w menu wymagała klucza tłumaczenia w każdym pliku locale — nav.home, nav.about, site.releases i tak dalej. Dodanie nowej strony oznaczało aktualizację N plików YAML. Teraz wystarczy menu.label w frontmatterze strony:

---
title: "Architecture guide"
menu:
  label: "Architecture"
  weight: 30
---

Nowa funkcja Twig content_item() odczytuje to bez dodatkowej konfiguracji:

{{ content_item('architecture-guide', 'en').menuLabel() }}

Polskie, niemieckie i francuskie treści demo dostały pełny przegląd przez wszystkie strony i wpisy.

1.1.2 — utwardzenie po przeglądzie#

1.1.2 to to, co wychodzi gdy siądziesz nad kodem przed taggiem i spojrzysz na niego świeżym okiem. Podczas przeglądu wypłynęły dwa bugi bezpieczeństwa i zostały naprawione przed wydaniem: open-redirect przez normalizację ścieżki (Request::getPathInfo() nie zwija powtórzonych slashy, więc /<default-locale>//evil.com wyprodukowałoby Location: //evil.com — przekierowanie cross-origin) oraz XSS na stronie wyników wyszukiwania, gdzie pole excerpt z Pagefind było wstrzykiwane do innerHTML bez escapowania.

Ficzer headline'owy to kanoniczne URL-e. Jeśli twoja domyślna locale to en, /en/blog/ i /blog/ były obie dostępne i renderowały tę samą treść — dwa indeksowalne URL-e dla jednej strony. Nowy event listener zwraca teraz 301 z /<default-locale>/... na wersję bez prefiksu, zanim router Symfony w ogóle ruszy.

Wewnętrznie, te wszystkie inline'owe bloki |json_encode|raw z JSON-LD rozsiane po szablonach zniknęły. Mały serwis StructuredDataBuilder plus dwie funkcje Twig (json_ld() i structured_data()) zastępują je płynnym, typowanym API. JSON_THROW_ON_ERROR jest włączone, więc zły bajt UTF-8 we frontmatterze rzuci wyjątkiem podczas renderu zamiast po cichu wysyłać <script>false</script>. Bazowe szablony rdzenia dla stron contact, default i projects też emitują teraz znaczniki Schema.org — bare deploy nie ma już słabszego SEO niż każdy przykład customizacji, który dostarczamy.

Demo jako żywy dowód#

Najbardziej satysfakcjonująca część tego wydania to nie kod — to co jest w docs/demo/. Nie motyw. Kompletna, czterojęzyczna strona która jest dołączona do repozytorium. Ma własny manual, dokumentację architektury, styleguide i blog wydań — wszystko działające, wszystko wyrenderowane przez ten sam system który dostajesz po git clone.

• Manual — instalacja, konfiguracja, struktura treści, frontmatter, komendy, deploy, zmienne środowiskowe, rozwiązywanie problemów
• Architektura — routing, pipeline treści, statyczny build, wyszukiwarka, wielojęzyczność, deployment
• Styleguide — każdy komponent udokumentowany z prawdziwymi tokenami SCSS
• Blog wydań — wpisy o każdej wersji, renderowane przez ten sam system

"Ufam ci że działa, ale pokaż" — to jest właśnie to. Demo nie jest przykładem, jest dowodem. Wielojęzyczne routowanie, pre-renderowanie statyczne, Pagefind, responsywne obrazki, formularz kontaktowy, RSS, sitemap — wszystko działa w treściach demo. Ktoś po świeżym git clone i ddev build widzi dokładnie tę stronę.

Linki#

Pełny changelog ze wszystkimi zmianami: CHANGELOG.md.

Zmiany breakingowe i migracja z 1.0.0: UPGRADE-1.1.md.

Repozytorium: GitHub / holas1337/notACMS — Apache 2.0.

Budowanie holas.pl wymagało napisania sporej ilości PHP, Twig i SCSS — i podejmowania decyzji architektonicznych, których cofnięcie byłoby uciążliwe. Przez cały czas używałem Claude Code jako AI pair programmera. Ten wpis opisuje jak ten workflow faktycznie wygląda, gdzie działa dobrze, a gdzie nadal wymaga ludzkiego osądu.

AGENTS.md — instrukcja obsługi dla AI#

Pierwsze praktyczne spostrzeżenie z tego projektu: asystent AI jest tak dobry jak instrukcje, które dostaje. Bez jawnych wytycznych Claude domyślnie generuje funkcjonalny, ale generyczny kod — rozsądne wybory, ale niekoniecznie takie, jakie sam byś podjął.

Rozwiązaniem jest AGENTS.md, plik w korzeniu projektu, który Claude Code czyta na początku każdej sesji. Dokumentuje:

• Zasady architektury — tylko klasy final, bez dziedziczenia, segregacja interfejsów, value objects zamiast tablic asocjacyjnych
• Styl kodu — strict types w każdym pliku, warunki Yoda, pusta linia przed return, konwencja przestrzeni nazw PSR-4
• Konwencje nazewnictwa — nazewnictwo interfejsów (ContentServiceInterface → ContentService), readonly value objects, constructor property promotion
• Polecenia DDEV — jak uruchomić środowisko, uruchomić buildy, sprawdzić jakość kodu
• Struktura treści — gdzie mieszkają pliki Markdown, jak działa frontmatter, jakie są konwencje slug URL

Z tym kontekstem Claude generuje kod zgodny z rzeczywistymi konwencjami projektu. Przeglądanie wygenerowanej klasy wygląda jak przeglądanie pull requesta od kolegi, który przeczytał przewodnik stylu — nie jak przeglądanie outputu wymagającego tłumaczenia na konwencje projektu.

EDITOR_GUIDE.md — delegowanie tworzenia treści#

Ta sama zasada dotyczy treści. EDITOR_GUIDE.md dokumentuje:

• Format i długość tytułu (poniżej 70 znaków, nazwy technologii uwzględnione, bez clickbaitu)
• Format opisu (120–160 znaków, bez "W tym wpisie...", zacznij od korzyści dla czytelnika)
• Struktura wstępu (2–3 zdania, bez powitania, najpierw problem)
• Konwencje treści (bloki kodu dla wszystkich poleceń, krótkie akapity, ponumerowane kroki dla procedur)
• Wymagania parytetu EN/PL (obie wersje równej głębokości, te same bloki kodu)
• Pola frontmatter i ich formaty

Dzięki temu przewodnikowi workflow tworzenia treści staje się:

1. Napisz wpis w surowej formie — pomysły, fragmenty kodu, struktura
2. Przekaż go Claude z: "sprawdź korektę, popraw angielski, przetłumacz na polski i wygeneruj dwa pliki .md z poprawnym frontmatter"
3. Przejrzyj wynik

Przewodnik jest na tyle konkretny, że Claude nie musi zadawać pytań wyjaśniających. Format tytułu, konwencja slug, wartości kategorii, format tagów, wzorzec ścieżki do obrazu — wszystko jest udokumentowane. Wynik jest gotowy do zacommitowania.

Generowanie obrazów z Draw Things i MCP#

Każdy wpis potrzebuje obrazu wyróżniającego (minimum 1200×630px). Dla holas.pl obrazy są generowane lokalnie za pomocą Draw Things przez integrację MCP (Model Context Protocol) w Claude Code.

Workflow:

1. Claude Code wywołuje mcp__draw-things__generate_image z promptem opisującym obraz, 4 równoległe warianty 1024×576px z steps=4
2. Najlepszy wariant jest wybierany z .generated/YYYY-MM-DD-nazwa-sesji/
3. ImageMagick skaluje go do rozmiaru produkcyjnego:

ddev exec convert .generated/sesja/obraz.jpg \
    -resize 1920x1080! -filter Lanczos -quality 92 \
    assets/images/wynik.jpg

4. Obraz jest przenoszony do content/blog/kategoria/nazwa-wpisu/files/ i referencjonowany w frontmatter

Katalog .generated/ jest w gitignore — zawiera jednorazowe podglądy. Tylko zatwierdzone obrazy zacommitowane do files/ stają się produkcyjnymi assetami.

MCP (Model Context Protocol) to właśnie to, co sprawia że to działa: standardowy interfejs łączący asystentów AI z zewnętrznymi narzędziami. Claude Code łączy się z Draw Things działającym lokalnie, przestrzeniami Hugging Face i innymi serwisami bez opuszczania sesji deweloperskiej. Generowanie obrazów dzieje się na lokalnej maszynie — bez limitu API, bez zewnętrznego serwisu, bez kosztu per obraz.

Co AI robi dobrze#

Boilerplate i wzorce — generowanie nowego serwisu z interfejsem, value objectem i poprawną kolejnością importów jest natychmiastowe. Struktura jest spójna z resztą bazy kodu, bo konwencje są udokumentowane.

SCSS z opisu — opisanie układu komponentu słowami i otrzymanie działającego SCSS z nazwami zmiennych projektu jest szybsze niż pisanie od podstaw.

Tłumaczenie — polska i angielska treść równej jakości. Konkretność przewodnika redakcyjnego w kwestii tego, co "równa jakość" oznacza (te same bloki kodu, ta sama głębokość, nie streszczenie) daje tłumaczenia niewymagające znaczącej edycji.

Powtarzalna praca strukturalna — generowanie list przekierowań nginx, aktualizowanie frontmatter w wielu plikach, pisanie wpisów mapy strony — zadania z jasnymi zasadami, ale wieloma instancjami.

Pozostawanie w kontekście — Claude Code czyta pliki projektu, rozumie istniejące wzorce i generuje kod, który pasuje bez mówienia mu, co robi każda klasa.

Gdzie nadal potrzebny jest ludzki osąd#

Decyzje architektoniczne — które abstrakcje wprowadzić, kiedy value object jest uzasadniony, jak ustrukturyzować pipeline treści — wymagają rozumienia kompromisów w sposób wykraczający poza dopasowywanie wzorców. AI generuje wiarygodne opcje; decyzja nadal należy do człowieka.

Estetyka designu — zmienne SCSS mogą być generowane, ale decyzja czy paleta kolorów dobrze wygląda na ciemnym tle w stylu terminala wymaga oczu i gustu.

Głos treści — przewodnik redakcyjny ujmuje konwencje tonu, ale faktyczne pomysły — co warto pisać, który kąt jest interesujący — pochodzą z doświadczenia, nie z promptu.

Przeglądanie outputu AI — kod i treść nadal muszą być czytane. Kod generowany przez AI wygląda wiarygodnie; wymaga developera, żeby zauważyć, gdy coś jest technicznie poprawne, ale architektonicznie złe.

Praktyczny wynik#

Cała strona — architektura, frontend, pipeline treści, formularz kontaktowy, skrypty deploymentu, ta seria wpisów blogowych — została zbudowana z Claude Code. Inwestycja czasu w AGENTS.md i EDITOR_GUIDE.md zwróciła się natychmiast: mniej czasu na korygowanie stylu, mniej czasu na tłumaczenie tych samych konwencji sesja po sesji, więcej czasu na faktyczną pracę.

Najbardziej zaskakującą korzyścią była treść. Napisanie wpisu w surowej formie, korekta, tłumaczenie na angielski i konwersja do dwóch poprawnie ustrukturyzowanych plików .md z prawidłowym frontmatter w jednym kroku — to usuwa wystarczająco dużo tarcia, że publikowanie faktycznie się dzieje.

Architektura zbudowana w ten sposób nie tylko produkuje łatwy w utrzymaniu kod — daje mierzalne wyniki. Następny wpis omawia wyniki Lighthouse: co napędza każdy z czterech wskaźników i dlaczego większość z tego wynika z architektury, nie z pracy optymalizacyjnej.

Jednym z celów dla holas.pl było środowisko deweloperskie tak proste jak produkcyjne. Brak bazy danych do uruchomienia, brak ręcznej konfiguracji sieci Docker, brak pięciominutowej sekwencji startowej. Efektem jest konfiguracja oparta na DDEV uruchamiająca się jednym poleceniem i stos produkcyjny działający w dwóch kontenerach.

Development z DDEV#

DDEV zarządza lokalnym środowiskiem deweloperskim. Cała konfiguracja jest w .ddev/config.yaml:

name: holas-pl
type: php
php_version: "8.5"
webserver_type: nginx-fpm
nodejs_version: "22"
omit_containers: [db]
web_environment:
  - APP_ENV=dev

Linia omit_containers: [db] jest znacząca — nie ma bazy danych, więc nie ma kontenera bazy danych. Domyślna konfiguracja MySQL/MariaDB DDEV jest całkowicie pominięta. ddev start uruchamia nginx + PHP-FPM i nic więcej.

W developmencie drzewo treści jest przebudowywane przy każdym żądaniu, więc edycja pliku Markdown i odświeżenie przeglądarki od razu pokazuje zmianę. Brak cache do czyszczenia. Pasek narzędzi debugowania Symfony jest dostępny. Wpisy draft są widoczne.

Polecenie build#

ddev build uruchamia pełny pipeline:

rm -rf var/dart-sass              # usuwa binarny plik specyficzny dla architektury (patrz niżej)
php bin/console cache:clear
php bin/console sass:build        # kompiluje SCSS przez dart-sass
php bin/console asset-map:compile # fingerprinting assetów
php bin/console app:build         # renderuje wszystkie URL do public/static/
npx pagefind --site public/static --output-path public/pagefind

Po tym public/static/ zawiera kompletną stronę jako pliki HTML. nginx serwuje z tego katalogu. Krok dart-sass usuwa binarny plik specyficzny dla platformy przed buildem, aby wymusić świeże pobranie — więcej o tym poniżej.

Kontrola jakości kodu#

ddev code-check uruchamia cztery sprawdzenia po kolei:

composer validate --strict
composer audit --no-dev          # sprawdza znane CVE w zależnościach
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/phpstan analyse       # poziom 6

ddev code-fix automatycznie naprawia problemy PHP CS Fixer i ponownie uruchamia sprawdzenie. PHPStan poziom 6 wyłapuje brakujące type hinty, złe typy argumentów i nieznane metody przed dotarciem do produkcji.

Styleguide#

Strona dostępna tylko w deweloperskim środowisku pod adresem /styleguide/ dokumentuje każdy komponent UI używając rzeczywistych klas CSS — nie wrapperów ani migawek. Strona jest serwowana tylko w środowisku dev (kontroler rzuca 404 w produkcji) i nie jest uwzględniana w statycznym buildzie.

Wartość styleguide'a jest w developmencie: zmiana SCSS komponentu natychmiast aktualizuje styleguide. Nie ma osobnego systemu designu do synchronizowania.

Pipeline assetów bez Node.js#

SCSS jest kompilowany przez symfonycasts/sass-bundle, który opakowuje dart-sass i nie wymaga instalacji Node.js. Jeden punkt wejścia assets/styles/app.scss importuje wszystkie pliki częściowe. W developmencie kompiluje w locie. W produkcji php bin/console sass:build uruchamia się przed buildem.

Moduły JavaScript są obsługiwane przez AssetMapper Symfony — bez webpacka, bez Vite, bez rollupa. Skrypty są ładowane jako zwykłe tagi <script src="..."> z nazwami plików zawierającymi hash treści. Import map rejestruje tylko główny punkt wejścia app.js; inne skrypty (formularz kontaktowy, wyszukiwanie, baner cookies) są ładowane osobno przez {{ asset('script.js') }} w szablonach.

Problem z binarnym plikiem dart-sass: symfonycasts/sass-bundle pobiera binarny plik dart-sass specyficzny dla platformy do var/dart-sass/. Plik binarny skompilowany na maszynie deweloperskiej (x86_64) nie uruchomi się w kontenerze produkcyjnym Docker (również x86_64 w tym przypadku, ale ścieżka i wersja binarna mogą się różnić). Rozwiązanie jest proste: usuń plik binarny przed każdym buildem i pozwól dart-sass pobrać właściwy dla bieżącej platformy.

Produkcja: dwa kontenery#

Produkcyjny docker-compose.yaml:

services:
  nginx:
    image: nginx:alpine
    volumes:
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - .:/app:ro
    depends_on:
      - php

  php:
    build:
      context: .
      dockerfile: docker/Dockerfile
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - .:/app

Dwa kontenery: nginx i PHP-FPM. Brak kontenera bazy danych. nginx montuje projekt jako tylko do odczytu; PHP-FPM działa jako użytkownik hosta, aby uniknąć problemów z uprawnieniami plików cache Symfony.

Obraz PHP (docker/Dockerfile) to php:8.5-fpm-alpine z tylko tym, co potrzebne: icu-dev (Symfony intl), nodejs i npm (dla kroku budowania Pagefind), unzip, git i Composer.

Deployment#

Cały deployment to jeden skrypt ./deploy.sh --prod:

1. docker compose down
2. docker compose build --pull — przebudowuje obraz PHP od zera
3. docker compose up -d
4. composer install --no-dev --optimize-autoloader
5. php bin/console cache:clear
6. rm -rf var/dart-sass — usuwa plik binarny specyficzny dla architektury
7. php bin/console sass:build
8. php bin/console asset-map:compile
9. php bin/console app:build — renderuje cały statyczny HTML
10. npx --yes pagefind --site public/static --output-path public/pagefind

Build uruchamia się wewnątrz kontenera PHP, gdzie znana jest poprawna architektura CPU. Po kroku 10 nginx już serwuje statyczne pliki poprzedniego buildu. Nowe pliki zastępują je na poziomie systemu plików. Istnieje krótkie okno, w którym częściowy build jest live, ale dla portfolio z niewielkim ruchem jest to akceptowalne bez złożoności blue-green deploymentu.

Brak pipeline'u CI/CD, brak środowiska stagingowego. Deployment to ssh server, cd holas.pl, git pull, ./deploy.sh --prod.

Porównanie z WordPressem#

Pełny produkcyjny stos WordPress wymagał: PHP-FPM, MySQL, warstwy cache (Redis lub system plików), uruchamiania zaplanowanych zadań dla wp-cron i wystarczająco dużo RAM, żeby utrzymać MySQL w pamięci podręcznej. Aktualizacje dowolnego komponentu wymagały przestoju lub starannego sekwencjonowania.

Obecny stos to dwa kontenery. Raspberry Pi 5 obsługuje je bez presji na pamięć. Deployment to skrypt shell. Cała baza kodu, treść i konfiguracja mieszczą się w jednym repozytorium git. Backup to git push.

Kolejny wpis z serii opisuje najbardziej niekonwencjonalną część tego projektu: budowanie całej strony z Claude Code jako AI pair programmerem i używanie narzędzi MCP do lokalnego generowania obrazów.

Rozwiązaniem jest globalny CLAUDE.md — trwały plik instrukcji, który uczy Claude'a, po które narzędzie sięgnąć w zależności od typu zapytania. Ten wpis opisuje mój setup, drzewo decyzyjne, które zbudowałem, i jak możesz stworzyć własne dla swojego stosu technologicznego.

Problem: za dużo narzędzi, brak strategii#

Serwery MCP dają Claude Code supermoce: automatyzację przeglądarki, śledzenie błędów, wyszukiwanie dokumentacji, integrację z IDE. Ale więcej narzędzi oznacza więcej wyborów, a bez wskazówek Claude podejmuje rozsądne, ale nieoptymalne decyzje.

Typowe problemy, które zaobserwowałem:

• Złe narzędzie do zadania — odpytywanie Context7 o "najnowszą wersję Symfony" (ma tylko dokumentację, nie metadane o wydaniach) zamiast Perplexity
• Droga ścieżka zamiast taniej — używanie Grepa do szukania route'ów Symfony w wielu plikach zamiast zapytania JetBrains MCP o strukturalną listę
• Pominięcie specjalisty — brak sprawdzenia Sentry przy błędzie produkcyjnym, kiedy stack trace natychmiast ujawniłby przyczynę
• Zbędne zapytania — próbowanie wielu narzędzi po kolei, kiedy pamięć mogłaby od razu skierować do właściwego

Rozwiązaniem są jawne reguły routingu zapisane w globalnym CLAUDE.md. Claude czyta ten plik na początku każdej sesji, więc drzewo decyzyjne jest zawsze dostępne.

Mój stos MCP#

Oto sześć serwerów MCP, których używam, i w czym każdy jest najlepszy.

Context7 — dokumentacja bibliotek i frameworków#

Context7 serwuje wersjonowaną dokumentację z przykładami kodu. Podajesz nazwę biblioteki i pytanie, a on zwraca odpowiednią sekcję z oficjalnej dokumentacji.

Workflow: resolve-library-id (znajdź bibliotekę) → query-docs (pobierz dokumentację do konkretnego pytania). Obsługuje wersjonowane zapytania — mogę odpytać /sylius/sylius/v1.14.6 bezpośrednio, nie tylko "latest".

Najlepszy do:

• Sygnatur metod i przykładów konfiguracji
• Poradników migracji między wersjami frameworków
• Wzorców z oficjalnej dokumentacji (formularze Symfony, mapowania Doctrine, filtry API Platform)

Nie radzi sobie z:

• Aktualnymi numerami wersji i datami wydań (ma dokumentację, nie metadane)
• Funkcjami języka PHP (PHP nie jest biblioteką z wersjonowaną dokumentacją w Context7)
• Poradnikami bezpieczeństwa i CVE
• Czymkolwiek wymagającym informacji w czasie rzeczywistym

Perplexity — aktualne fakty i research#

Perplexity to wyszukiwarka z AI w czterech trybach: search (wyniki z cytatami ze źródeł), ask (odpowiedzi AI przez sonar-pro), research (dogłębna analiza wieloźródłowa, 30+ sekund) i reason (logiczne rozumowanie krok po kroku).

Najlepszy do:

• Najnowszych numerów wersji, dat wydań, harmonogramów EOL
• Poradników bezpieczeństwa i szczegółów CVE
• Funkcji języka PHP i RFC (property hooks, asymmetric visibility — tego nie ma w Context7)
• Cen usług zewnętrznych (koszty API, porównania hostingów)
• Ogólnych dobrych praktyk programistycznych i benchmarków

Kluczowa rola: Perplexity wypełnia każdą lukę Context7. Kiedy Context7 nic nie zwraca albo zwraca nieaktualne dane, Perplexity prawie zawsze ma odpowiedź.

JetBrains — inteligencja kodu na poziomie IDE#

To serwer MCP, który oszczędza najwięcej tokenów. JetBrains MCP łączy Claude Code z indeksem Twojego IDE — tym samym, który napędza autouzupełnianie, go-to-definition i refaktoryzację. Bazowy JetBrains MCP dostarcza generyczne narzędzia (wyszukiwanie plików, lookup symboli, wyszukiwanie tekstowe, komendy terminala), a pluginy frameworkowe rozszerzają go o specjalistyczne narzędzia — plugin Symfony dodaje listowanie route'ów, wyszukiwanie serwisów, inspekcję encji Doctrine i analizę Twiga.

Mój typowy workflow: Wklejam link do ticketu Jira do konwersacji. Claude czyta zadanie przez Atlassian MCP, a potem używa JetBrains MCP do szybkiego rekonesansu kodu — znajdując odpowiednie serwisy, sprawdzając definicje route'ów, inspekcjonując pola encji — zanim napisze choćby jedną linię kodu. Ten krok "najpierw przeanalizuj" wyłapuje nieporozumienia wcześnie i daje Claude'owi kontekst do zadawania lepszych pytań wyjaśniających.

Możliwości specyficzne dla Symfony (przez plugin Symfony):

• list_symfony_routes_controllers — wszystkie route'y z kontrolerem, ścieżką, metodami. Jedno wywołanie zamiast grepowania atrybutów w dziesiątkach plików
• locate_symfony_service — znajdź definicję dowolnego serwisu po pełnej nazwie klasy
• list_doctrine_entity_fields — pola encji, typy i relacje w ustrukturyzowanym formacie
• list_symfony_commands, list_symfony_forms — komendy konsolowe i typy formularzy w jednym widoku

Przykład oszczędności tokenów: Znalezienie wszystkich route'ów pasujących do /api/ w projekcie Symfony:

• Bez JetBrains: Grep po #[Route w src/Controller/, odczyt każdego pasującego pliku, parsowanie atrybutów route'ów, konfrontacja z _routes.yaml. Łatwo 5-10 wywołań narzędzi i tysiące tokenów treści plików.
• Z JetBrains: Jedno wywołanie list_symfony_routes_controllers zwraca strukturalną, filtrowalną listę. Gotowe.

Przydatny też do: Indeksowane wyszukiwanie tekstowe (search_in_files_by_text), wyszukiwanie plików po nazwie, lookup symboli, uruchamianie komend terminala w IDE, budowanie i testowanie.

Chrome DevTools — automatyzacja przeglądarki#

Chrome DevTools MCP pozwala Claude'owi sterować przeglądarką: nawigować po URL-ach, klikać elementy, wypełniać formularze, robić zrzuty ekranu, inspekcjonować żądania sieciowe, uruchamiać JavaScript i wykonywać audyty Lighthouse.

Najlepszy do:

• Wizualnego testowania zmian UI po modyfikacji szablonów lub CSS
• Audytów wydajności i dostępności Lighthouse
• Debugowania problemów frontendowych (błędy w konsoli, żądania sieciowe)
• Weryfikacji responsywności przy różnych szerokościach viewportu

Sentry — śledzenie błędów produkcyjnych#

Sentry MCP łączy Claude'a z systemem śledzenia błędów. Może wyszukiwać issues, pobierać stack trace'y, analizować błędy z AI Sentry (Seer) i sprawdzać informacje o wydaniach i wdrożeniach.

Workflow, który sprawia, że to jest wartościowe:

1. Zauważasz błąd (lub zgłasza go użytkownik)
2. Claude odpytuje Sentry: "wyszukaj błędy 500 z ostatnich 24 godzin"
3. Sentry zwraca stack trace, liczbę dotkniętych użytkowników, timestampy first/last seen
4. Claude czyta odpowiedni plik źródłowy, identyfikuje przyczynę i proponuje fix
5. Cały cykl debugowania odbywa się bez opuszczania terminala

Najlepszy do:

• Badania błędów produkcyjnych z pełnymi stack trace'ami
• Rozumienia częstotliwości i wzorców błędów (czy jest nowy? czy się pogarsza?)
• Korelowania błędów z ostatnimi wdrożeniami

Atlassian/Jira — zarządzanie zadaniami#

Jira MCP zapewnia pełne zarządzanie cyklem życia issues: tworzenie, odczyt, edycję, przejścia statusów, komentowanie i wyszukiwanie JQL.

Najlepszy do:

• Czytania specyfikacji zadań przed rozpoczęciem pracy
• Aktualizowania statusu issues w trakcie pracy
• Dodawania technicznych komentarzy do issues dla widoczności zespołu
• Wyszukiwania JQL do znajdowania powiązanych issues lub sprawdzania bieżącego sprintu

Drzewo decyzyjne#

Sercem globalnego CLAUDE.md jest tablica routingu, która mapuje typy zapytań na najlepsze narzędzie. Oto faktyczna treść z mojego pliku:

## Search & Research — Tool Decision Tree

### When to use Context7
**Best for**: library/framework API docs with clean code examples
- Versioned library docs (Sylius, Doctrine, API Platform, Symfony, GitHub Actions)
- Official method signatures, configuration examples, how-to patterns
- Concise, authoritative answers directly from official source
- `resolve-library-id` first, then `query-docs`
- **Fails for**: current version/release info, PHP language features,
  security CVEs, pricing, general programming

### When to use Perplexity
**Best for**: anything current, factual, or not a library doc
- Latest versions, release dates, EOL schedules
- Security advisories, CVEs, vulnerability details
- PHP language features (property hooks, new syntax)
- External service pricing
- General programming best practices, benchmarks
- Supplement when Context7 fails or for real-world context

### When to use WebSearch
- Official blog posts / release announcements
- As last resort or to supplement

Kluczowy wzorzec: każda sekcja zaczyna się od "best for" (kiedy wybrać to narzędzie) i kończy "fails for" (kiedy je pominąć). Claude korzysta z obu sygnałów — routingu pozytywnego i negatywnego.

Tablica benchmarków#

Przepuściłem te same 10 typów zapytań przez Context7, Perplexity i WebSearch i oceniłem wyniki. Ta tablica znajduje się w globalnym CLAUDE.md, żeby Claude mógł się do niej odwoływać przy podejmowaniu decyzji:

Wzorzec jest czytelny: Context7 jest doskonały do wersjonowanej dokumentacji, ale dostaje zero w czymkolwiek wymagającym aktualnych lub rzeczywistych danych. Perplexity pokrywa niemal wszystko. WebSearch jest najsilniejszy w blogpostach i ogłoszeniach o wydaniach.

Umieszczenie tej tabeli w globalnym CLAUDE.md daje Claude'owi ilościową podstawę do wyboru narzędzia, nie tylko reguły.

Jak działa globalna pamięć#

Claude Code obsługuje globalny plik instrukcji w ~/.claude/CLAUDE.md. Ten plik jest ładowany na początku każdej konwersacji, niezależnie od projektu. To właściwe miejsce na reguły routingu narzędzi, bo serwery MCP są konfigurowane globalnie, nie per projekt.

Porównanie z projektowym AGENTS.md:

Struktura globalnego CLAUDE.md#

Globalny CLAUDE.md działa najlepiej, gdy jest ustrukturyzowany jak podręcznik referencyjny, nie narracja. Claude skanuje go na początku sesji — czytelne nagłówki i jawne reguły sprawiają, że ten skan jest skuteczny.

Wskazówki z mojego doświadczenia:

1. Zacznij od reguły decyzyjnej, nie od opisu. "Best for: versioned library docs" jest bardziej użyteczne niż "Context7 is a documentation server that..."
2. Uwzględnij tryby awarii. "Fails for: current versions" zapobiega próbom użycia Context7 do zapytań, z którymi sobie nie radzi.
3. Dodaj inwentarz serwerów. Wymień każdy serwer MCP z jego narzędziami — Claude może się do tego odwołać, gdy potrzebuje funkcji, której jeszcze nie używał.
4. Używaj konkretnych przykładów. "Latest Symfony version → Perplexity" jest lepsze niż "use Perplexity for current data."
5. Aktualizuj przy zmianach narzędzi. Dodałeś nowy serwer MCP? Zaktualizuj plik. Usunąłeś jeden? Usuń jego wpis. Nieaktualne reguły routingu są gorsze niż brak reguł.

Zbuduj własne drzewo#

Konkretne serwery MCP nie mają znaczenia — liczy się wzorzec. Niezależnie od tego, czy używasz Cursora, Windsurf czy Claude Code, czy piszesz w Pythonie czy Go, zasada jest ta sama: naucz swojego asystenta AI, po które narzędzie sięgnąć.

Krok po kroku:

1. Wymień swoje serwery MCP (lub równoważne integracje narzędziowe) i do czego każdy służy
2. Zidentyfikuj nakładanie się — gdzie dwa narzędzia mogą odpowiedzieć na to samo zapytanie? (Context7 i Perplexity obsługują dokumentację Symfony, ale z różnymi mocnymi stronami)
3. Zbenchmarkuj — przepuść te same 5-10 reprezentatywnych zapytań przez każde nakładające się narzędzie. Oceń wyniki. To daje dane, nie przeczucie.
4. Napisz reguły routingu — dla każdego narzędzia napisz sekcje "best for" i "fails for" z konkretnymi typami zapytań
5. Dołącz benchmark — tablica daje Twojemu AI ilościowy punkt odniesienia, nie tylko instrukcje
6. Iteruj — pierwsza wersja nie będzie idealna. Kiedy Claude wybierze złe narzędzie, zaktualizuj plik. Po kilku sesjach routing się doszlifuje.

Mój globalny CLAUDE.md zaczął się jako lista serwerów MCP z jednolinijkowymi opisami. Po kilku tygodniach obserwacji, gdzie Claude podejmował nieoptymalne wybory, ewoluował w drzewo decyzyjne opisane powyżej. Tablica benchmarków była największą pojedynczą poprawą — zamieniła niejasne reguły "preferuj X nad Y" w konkretne dane, na podstawie których Claude mógł działać.

Inwestycja jest niewielka (godzina na konfigurację, kilka minut na aktualizację) a zwrot się kumuluje: mniej zmarnowanych tokenów, szybsze odpowiedzi i mniej czasu na korygowanie wyborów narzędzi w trakcie konwersacji.

holas.pl jest stroną statyczną z jednym wyjątkiem: formularzem kontaktowym. Każdy wpis blogowy, strona kategorii i strona statyczna to wstępnie wyrenderowany plik HTML serwowany przez nginx. Formularz kontaktowy to jedyny endpoint uruchamiający PHP.

To jedno wyjście rodzi konkretne pytanie bezpieczeństwa: jak chronić formularz na stronie statycznej przed botami i atakami CSRF, gdy nie ma sesji?

Problem CSRF na stronach statycznych#

Standardowa ochrona CSRF działa przez osadzenie tokena w formularzu powiązanego z sesją użytkownika. Przy przesyłaniu formularza serwer weryfikuje, czy token pasuje do tego z sesji.

Strony statyczne nie mają sesji. Strona kontaktowa jest generowana raz podczas ddev build i serwowana jako plik. Nie może generować tokena per użytkownik w czasie renderowania. Wbudowana csrf_protection Symfony jest więc jawnie wyłączona w formularzu kontaktowym:

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'csrf_protection' => false,  // celowe — strona statyczna, brak sesji
    ]);
}

Wyłączenie ochrony CSRF to właściwa decyzja. Alternatywa — dodanie dynamicznego endpointu PHP tylko do generowania tokenów dla formularza — przywróciłaby problem PHP-przy-każdym-żądaniu dla strony, która poza tym go nie potrzebuje.

Cloudflare Turnstile jako zamiennik#

Cloudflare Turnstile to alternatywa dla CAPTCHA działająca po stronie klienta, potwierdzająca człowieczeństwo użytkownika i dostarczająca jednorazowy token weryfikowalny po stronie serwera. Zastępuje CSRF jako warstwa zapobiegania botom.

Przepływ formularza:

1. Strona kontaktowa jest serwowana jako statyczny HTML z osadzonym widżetem Turnstile (klucz strony jest wbudowany podczas buildu)
2. Turnstile uruchamia swoje wyzwanie niewidocznie; po sukcesie wywołuje window.onTurnstileSuccess(token), który zapisuje token do ukrytego pola
3. contact.js przechwytuje zdarzenie submit formularza i wysyła dane przez fetch() zamiast standardowego wysłania formularza
4. Endpoint PHP otrzymuje przesłanie, weryfikuje pola formularza, następnie weryfikuje token Turnstile przez API Cloudflare
5. Tylko jeśli oba sprawdzenia przejdą, e-mail jest wysyłany

Weryfikacja po stronie serwera to kluczowy krok:

final class TurnstileValidator
{
    public function verify(string $token, string $remoteIp): bool
    {
        try {
            $response = $this->httpClient->request('POST', 'https://challenges.cloudflare.com/turnstile/v0/siteverify', [
                'body' => [
                    'secret'   => $this->secretKey,
                    'response' => $token,
                    'remoteip' => $remoteIp,
                ],
            ]);

            $data = $response->toArray();

            return true === ($data['success'] ?? false);
        } catch (\Throwable $e) {
            $this->logger->error('Weryfikacja Turnstile nie powiodła się: '.$e->getMessage());

            return false;
        }
    }
}

Walidator zawodzi bezpiecznie — każdy wyjątek zwraca false i blokuje przesłanie. Pusty lub brakujący token również zwraca false natychmiast.

Minimalna powierzchnia ataku PHP#

Cała powierzchnia PHP aplikacji w produkcji to dwa wzorce URL:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
    fastcgi_read_timeout 30;
}

Wszystko inne — każdy wpis blogowy, każda strona kategorii, mapa strony, kanał RSS, strona wyszukiwania — jest obsługiwane przez nginx serwujący pliki statyczne. PHP-FPM nie jest nigdy wywoływane przy dostarczaniu treści. Powierzchnia ataku warstwy PHP to jeden endpoint POST.

Content Security Policy#

Konfiguracja nginx stosuje rygorystyczny CSP przy każdej odpowiedzi:

add_header Content-Security-Policy
    "default-src 'self';
     script-src  'self' challenges.cloudflare.com;
     style-src   'self' 'unsafe-inline';
     img-src     'self' data:;
     frame-src   challenges.cloudflare.com;
     connect-src 'self' challenges.cloudflare.com;"
    always;

Jedyną dozwoloną zewnętrzną domeną jest challenges.cloudflare.com, której Turnstile wymaga dla swojego skryptu, iframe i wywołania API. Brak Google Analytics, skryptów CDN, piksela Facebooka. script-src nie ma 'unsafe-inline' ani 'unsafe-eval' — cały JavaScript jest ładowany z plików z hashami przez Symfony AssetMapper.

'unsafe-inline' w style-src to celowy kompromis: widżet Turnstile wstrzykuje style inline, których nie można uniknąć bez nonce CSP, a AssetMapper aktualnie nie wstrzykuje nonces. Wszystko inne jest zablokowane.

Dodatkowe nagłówki bezpieczeństwa#

add_header X-Frame-Options        "SAMEORIGIN"                       always;
add_header X-Content-Type-Options "nosniff"                          always;
add_header Referrer-Policy        "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy     "camera=(), microphone=(), geolocation=()" always;

Ukryte pliki są blokowane:

location ~ /\. { deny all; }

HSTS jest obsługiwane przez Cloudflare, więc nie ma nagłówka Strict-Transport-Security w konfiguracji nginx — byłby zbędny.

Wynik#

Formularz kontaktowy działa bez sesji, bez tokenów CSRF i bez JavaScriptu wymaganego do czegokolwiek poza samym wysłaniem formularza. Strona renderuje się w pełni jako statyczny HTML. Przesłania botów są blokowane przez weryfikację Turnstile po stronie serwera. Endpoint PHP jest nieosiągalny dla czegokolwiek poza żądaniami POST do /api/contact.

W porównaniu z WordPressem z wtyczką formularza kontaktowego, powierzchnia ataku zmalała z "PHP działającego przy każdym żądaniu, wp-admin wystawione, XML-RPC włączone, 22 wtyczki, każda mogąca mieć lukę" do "jeden endpoint POST z weryfikacją Cloudflare".

Następny wpis opisuje środowisko deweloperskie — DDEV, pipeline buildu i deployment do produkcji w dwóch kontenerach Docker.

Kod jest open-source na licencji Apache 2.0 — zobacz GitHub / notACMS. Zawiera 368 testów PHPUnit, CI/CD przez GitHub Actions i wzorzec lokalnych nadpisań który pozwala użytkownikom customizować szablony, CSS i tłumaczenia bez forkowania.

Architektura#

Cała treść żyje w plikach Markdown z YAML frontmatterem:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← wersja angielska
│           ├── pl.md   ← wersja polska
│           └── files/  ← obrazki, serwowane z /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder skanuje system plików, parsuje każdy plik przez league/commonmark (GitHub Flavoured Markdown + YAML frontmatter) i buduje typowane ContentTree — indeks w pamięci wszystkich postów i stron dla danego locale. Tagi, kategorie, miesiące archiwum i mapy URL są obliczane z tego indeksu.

Statyczny build używa sub-requestów Symfony: HttpKernelInterface::handle() z SUB_REQUEST renderuje każdy URL przez pełny kernel bez dotykania sieci. Jeśli URL działa w development, będzie w buildzie statycznym. Brak osobnego silnika szablonów, brak konfiguracji buildu.

Kluczowe funkcje#

• Wielojęzyczność — sparowane en.md + pl.md w tym samym katalogu, automatyczne mapowanie tłumaczeń, tagi hreflang, przełącznik języka
• Wyszukiwarka — statyczny indeks oparty na WASM przez Pagefind, po stronie klienta, bez Elasticsearch ani Algolia
• Responsywne obrazki — automatyczne generowanie srcset przez ImageMagick, konfigurowalne szerokości wariantów
• Drafty i zaplanowane posty — dev-only przełączniki podglądu, zaplanowane posty publikowane automatycznie w czasie buildu
• Formularz kontaktowy — Cloudflare Turnstile CAPTCHA, ciasny CSP, pojedynczy endpoint POST
• Styleguide — strona tylko dla dev dokumentująca każdy komponent z prawdziwymi klasami CSS
• Wzorzec lokalnych nadpisań — katalog local/ scala się na bazę w czasie buildu, customizacja bez forkowania

Stos technologiczny#

• PHP 8.5, Symfony 7.x
• Szablony Twig, SCSS (dart-sass przez symfonycasts/sass-bundle)
• Symfony AssetMapper (bez webpacka, bez Vite, bez pipeline'u Node.js)
• nginx + PHP-FPM (dwa kontenery Docker na produkcji)
• Pagefind do wyszukiwania
• PHPUnit 13, PHPStan level 6, Rector, PHP CS Fixer

Dlaczego go zbudowałem?#

Hugo, Jekyll i Eleventy były oczywistymi kandydatami. Wybrałem budowę customowej aplikacji Symfony bo znam Symfony dobrze, a posiadanie pełnego stacka okazało się mieć realne zalety: te same szablony, kontrolery i pipeline treści obsługują zarówno development jak i produkcję. Nie ma "silnika szablonów build-time" oddzielonego od "silnika szablonów runtime." To po prostu Symfony.

Pełna historia dlaczego WordPress musiał odejść jest w Dlaczego odszedłem od WordPressa. Głębokie zanurzenie w architekturę jest w Symfony jako generator statycznych stron.

Open Source#

notACMS jest dostępny na GitHubie na licencji Apache 2.0. Przygotowanie do wydania — testy, audyt AI, poprawki bezpieczeństwa, wzorzec lokalnych nadpisań — jest udokumentowane w serii o open-source.

Po podjęciu decyzji o odejściu od WordPressa pytanie brzmiało: czym go zastąpić? Hugo, Jekyll i Eleventy były oczywistymi kandydatami. Zdecydowałem się zbudować własną aplikację Symfony — nie dlatego, że istniejące narzędzia są niewystarczające, ale dlatego, że Symfony znam dobrze, a posiadanie pełnego stosu okazało się mieć realne zalety.

Podstawowa idea#

Strona działa w dwóch trybach:

• Deweloperski — Symfony obsługuje żądania dynamicznie. Edytujesz plik Markdown, odświeżasz przeglądarkę, widzisz wynik. Standardowy workflow developerski Symfony z paskiem profilera.
• Build produkcyjny — jedno polecenie konsolowe renderuje każdy URL do pliku HTML na dysku. nginx serwuje te pliki bezpośrednio. PHP nie jest wywoływane przy dostarczaniu treści.

Te same szablony, kontrolery i pipeline treści obsługują oba tryby. Nie ma osobnego "silnika szablonów do budowania" oddzielnego od "silnika szablonów do działania". To po prostu Symfony.

Pipeline treści#

Cała treść mieszka w plikach Markdown z nagłówkiem YAML:

content/
├── blog/
│   └── tutorials/
│       └── moj-wpis/
│           ├── en.md   ← wersja angielska
│           ├── pl.md   ← wersja polska
│           └── files/  ← obrazy, serwowane pod /media/moj-wpis/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder skanuje system plików, parsuje każdy plik przez league/commonmark (GitHub Flavoured Markdown + nagłówki YAML) i buduje typowany ContentTree — indeks w pamięci wszystkich wpisów i stron dla danego locale. Tagi, kategorie, miesiące archiwum i mapy URL są wyliczane z tego indeksu.

ContentItem to obiekt wartości final readonly. Brak bazy danych, ORM, migracji. Dodanie wpisu oznacza stworzenie katalogu z dwoma plikami Markdown i uruchomienie buildu.

Polecenie build — sub-żądania Symfony#

Build statyczny używa techniki specyficznej dla Symfony, która odróżnia to podejście od Hugo czy Jekylla: wywołuje HttpKernelInterface::handle() w celu tworzenia sub-żądań — wewnętrznych wywołań PHP przechodzących przez pełne jądro Symfony bez dotyku sieci.

$request = Request::create($url);
$request->attributes->set('_static_build', true);
$response = $this->kernel->handle($request, HttpKernelInterface::SUB_REQUEST, false);

if ($response->getStatusCode() < 400) {
    file_put_contents($outputPath, $response->getContent());
}

Dla każdego URL — wpisów blogowych, stron kategorii, stron tagów, miesięcy archiwum, stron statycznych, stron błędów, kanałów RSS, mapy strony — polecenie build tworzy żądanie, przepuszcza je przez Symfony i zapisuje HTML na dysk. URL /blog/ staje się public/static/blog/index.html. URL /sitemap.xml staje się public/static/sitemap.xml.

Brak osobnego silnika szablonów do nauki. Brak konfiguracji buildu. Jeśli URL działa w developmencie, będzie w statycznym buildzie.

nginx serwuje wszystko#

W produkcji nginx obsługuje całe dostarczanie treści:

location / {
    try_files /static$uri/index.html /static$uri/index.xml /static$uri $uri =404;
}

# PHP tylko dla formularza kontaktowego
location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
}

Dla każdego przychodzącego URL nginx najpierw próbuje wstępnie wyrenderowanego pliku HTML. PHP-FPM jest wywoływane tylko dla /api/contact — jedynego dynamicznego endpointu. Każdy wpis blogowy, lista kategorii, strona tagów i strona statyczna to plik serwowany bezpośrednio z dysku. Raspberry Pi 5 obsługuje to banalnie.

Bez bazy danych#

Drzewo treści jest budowane z plików Markdown podczas budowania. W produkcji jest cache'owane bez ograniczeń czasowych w cache'u systemu plików Symfony (unieważniane i przebudowywane przy każdym deployu). W developmencie jest przebudowywane przy każdym żądaniu, żeby zmiany plików były natychmiast widoczne.

Brak MySQL, schematu, migracji, connection poolingu, wolnych zapytań. Dodawanie treści oznacza tworzenie plików i uruchamianie ddev build. Usuwanie treści oznacza usuwanie plików. Cała historia strony jest w gicie.

Wielojęzyczność bez bazy danych#

Zarówno polska, jak i angielska treść mieszka w tym samym katalogu:

content/blog/tutorials/moj-wpis/
    en.md  → slug: "blog/my-post"     → /blog/my-post/
    pl.md  → slug: "wpisy/moj-wpis"   → /pl/wpisy/moj-wpis/
    files/ → obrazy serwowane pod /media/moj-wpis/

Współlokalizacja to link translacji. Dwa pliki locale w tym samym katalogu są automatycznie traktowane jako tłumaczenia siebie nawzajem. TranslationMapBuilder buduje {directoryKey → {locale → url}} dla tagów hreflang i przełącznika języka. Bez pola translation_key, bez tabeli łączącej, bez synchronizacji do zarządzania.

Wyszukiwanie z Pagefind#

Wyszukiwanie to oparty na WASM statyczny indeks budowany przez Pagefind po wygenerowaniu plików HTML:

npx pagefind --site public/static --output-path public/pagefind

Pagefind czyta wstępnie wyrenderowany HTML, indeksuje regiony data-pagefind-body i generuje binarny indeks w public/pagefind/. Strona wyszukiwania ładuje ten indeks po stronie klienta przez dynamiczny import(). Brak Elasticsearch, Algolii, zapytań wyszukiwania po stronie serwera. Indeks to zbiór plików statycznych.

Prostota redesignu#

Zmiana wyglądu strony oznacza edycję szablonów Twig i SCSS. Brak biblioteki komponentów React do aktualizacji. Brak pipeline'u Node.js. Brak hierarchii motywów WordPress. Cały frontend to:

• assets/styles/app.scss — jeden punkt wejścia importujący pliki częściowe
• templates/ — szablony Twig
• symfonycasts/sass-bundle — kompiluje SCSS przez dart-sass, bez Node.js

Żeby zmienić schemat kolorów: edytuj _variables.scss. Żeby zmienić layout: edytuj szablon Twig. Uruchom ddev build i gotowe.

Kompromisy#

Głównym kompromisem w porównaniu z Hugo czy Jekyllem jest to, że to własny kod — ja go utrzymuję. Zaletą jest to, że jest dokładnie tym, czego potrzebuję, niczym więcej. Brak ekosystemu wtyczek do nawigowania, brak ścieżki aktualizacji do martwienia się, brak feature flag dla rzeczy, których nigdy nie użyję.

Jedyna naprawdę dynamiczna funkcja — formularz kontaktowy — jest omówiona w następnym wpisie.

To pierwszy wpis z serii dokumentującej migrację do własnego generatora stron statycznych opartego na Symfony. Kolejne wpisy omawiają architekturę, formularz kontaktowy, środowisko deweloperskie i budowanie strony z pomocą AI.

Taśmociąg aktualizacji#

WordPress regularnie wydaje aktualizacje bezpieczeństwa. Wtyczki wydają aktualizacje niezależnie. Motywy też. W spokojnym tygodniu miałem trzy pozycje w kolejce. W gorszy tydzień — piętnaście. Każda wymagała:

1. Kopii zapasowej bazy danych i plików
2. Zastosowania aktualizacji
3. Sprawdzenia, czy nic się nie posypało

Ten ostatni krok to największy problem. Wtyczki WordPressa wchodzą ze sobą w interakcje w sposób niemożliwy do przewidzenia. Aktualizacja wtyczki do cache'owania psuła wyniki wtyczki SEO. Aktualizacja wtyczki SEO zmieniała sposób generowania map strony. Każda aktualizacja to mały hazard.

Dla portfolio z wpisem co kilka miesięcy ten narzut na utrzymanie jest absurdalny.

Dziesiątki wtyczek do podstawowych funkcji#

Świeża instalacja WordPressa nie robi prawie nic. Żeby prowadzić przyzwoite portfolio blogowe, potrzebowałem wtyczek do:

• SEO — Yoast lub Rank Math, z własnym interfejsem, ustawieniami i cyklem aktualizacji
• Cache'owania — W3 Total Cache lub WP Super Cache, ze skomplikowaną konfiguracją
• Bezpieczeństwa — Wordfence lub podobna, skanowanie intruzji, blokowanie IP, codzienne raporty
• Formularza kontaktowego — Contact Form 7 lub Gravity Forms
• Kopii zapasowych — UpdraftPlus lub podobna, zwykle wysyłająca dane do zewnętrznego serwisu
• Wydajności — optymalizacja obrazów, lazy loading, minifikacja
• SMTP — bo WordPress domyślnie wysyła e-maile przez mail() w PHP, które trafiają do spamu

Każda wtyczka to kod, którego nie kontroluję, utrzymywany przez kogoś innego, potencjalnie porzucony jutro, działający przy każdym wczytaniu strony.

Kiedy zacząłem planować migrację, miałem 22 aktywne wtyczki.

Ataki botów i problemy z logowaniem#

Strona logowania do WordPressa jest dobrze znana botom. URL to zawsze /wp-admin/ lub /wp-login.php. Każdy bot w internecie to wie. Efekt: ciągłe próby włamania przez brute-force, przez całą dobę.

Wordfence ograniczał próby logowania, blokował podejrzane IP i wysyłał mi codzienne raporty o atakach. Działało — ale to kolejny element pochłaniający zasoby serwera na stronie, która w ogóle nie potrzebuje logowania użytkowników. Jedyną osobą logującą się byłem ja, raz w miesiącu.

XML-RPC to kolejny wektor ataku. WordPress domyślnie go włącza dla pingbacków i aplikacji mobilnej. Boty ciągle go sondują. Rozwiązaniem była reguła nginx blokująca ten endpoint — ale dowiedziałem się o tym dopiero po zobaczeniu ruchu w logach.

PHP i MySQL na Raspberry Pi#

holas.pl działa na własnym sprzęcie — najpierw Banana Pi, teraz Raspberry Pi 5. To sprawne płyty ARM, ale nie są maszynami serwerowymi. Uruchamianie PHP-FPM i MySQL jednocześnie dla bloga, który zmienia się raz w miesiącu, to czyste marnotrawstwo.

Typowe wczytanie strony WordPress na tym sprzęcie: PHP przetwarza żądanie, MySQL wykonuje kilka zapytań po treść wpisu, dane nawigacji, widżety paska bocznego i opcje strony, PHP renderuje szablony, każda aktywna wtyczka wykonuje swoje hooki. Wszystko to dla treści identycznej z poprzednim żądaniem i identycznej z następnym.

Ze stroną statyczną nginx serwuje wstępnie wyrenderowany plik HTML bezpośrednio z dysku. Procesor ARM ledwo się budzi. Strony ładują się szybciej niż WordPress zdążył przetworzyć żądanie.

Baza danych jako ryzyko#

Dziewiętnaście lat WordPressa to baza danych z tysiącami wierszy metadanych wpisów, opcji, rewizji i transientów. Wymaga:

• Regularnych kopii zapasowych (i testowania, że przywracanie faktycznie działa)
• Okazjonalnego czyszczenia — WordPress gromadzi śmieci: rewizje wpisów, wygasłe transienty, osierocone wiersze metadanych
• Monitorowania pod kątem uszkodzeń po nieoczystym wyłączeniu
• Ciągle działającego procesu MySQL, zużywającego pamięć

Portfolio blog to zbiór tekstów i obrazów. Przechowywanie go w relacyjnej bazie danych dodaje złożoności operacyjnej bez dodawania wartości.

Co zostało zachowane#

Treść. Wszystkie 26 wpisów zostało wyeksportowanych i przekonwertowanych do plików Markdown — tytuły, daty, kategorie, tagi, obrazy. Adresy URL zostały zachowane dokładnie: 25 indywidualnych przekierowań wpisów i 43 przekierowania ścieżek obrazów jest teraz wbudowanych w konfigurację nginx. Pozycje w wyszukiwarce przetrwały migrację nienaruszone.

Wszystko inne — baza danych, wtyczki, kolejka aktualizacji, strona logowania /wp-admin/ — zniknęło.

Następny wpis opisuje, co zastąpiło WordPressa: własna aplikacja Symfony generująca statyczne pliki HTML, serwowane przez nginx bez udziału PHP w dostarczaniu treści do odwiedzających.

Traefik to reverse proxy zaprojektowany dla środowisk kontenerowych. Obserwuje Docker socket, wykrywa uruchomione kontenery i automatycznie pobiera certyfikaty Let's Encrypt — bez certbota, bez crona, bez ręcznej konfiguracji per domena.

Konfiguracja składa się z dwóch części: jedna instancja Traefik działająca cały czas na serwerze oraz etykiety przy każdej usłudze, które mówią Traefik jak routować ruch i dla jakiej domeny wystawić certyfikat.

Część 1 — docker-compose.yml dla Traefik#

Uruchamiany raz na serwerze. Wszystkie pozostałe usługi przechodzą przez niego.

services:
    traefik:
        image: traefik:${TRAEFIK_VERSION}
        container_name: traefik
        command:
            - "--providers.docker=true"
            - "--providers.docker.exposedbydefault=false"
            - "--entrypoints.web.address=:80"
            - "--entrypoints.websecure.address=:443"
            # globalne przekierowanie HTTP → HTTPS
            - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
            - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
            # Let's Encrypt
            - "--certificatesResolvers.le.acme.email=${ACME_EMAIL}"
            - "--certificatesResolvers.le.acme.storage=acme.json"
            - "--certificatesResolvers.le.acme.tlsChallenge=true"
        restart: always
        ports:
            - 80:80
            - 443:443
        networks:
            - web
        volumes:
            - /etc/localtime:/etc/localtime:ro
            - /var/run/docker.sock:/var/run/docker.sock
            - ./acme.json:/acme.json
        labels:
            - traefik.http.middlewares.gzip.compress=true

networks:
    web:
        external: true

Kilka rzeczy wartych uwagi:

• exposedbydefault=false — Traefik ignoruje kontenery, chyba że jawnie się zgłoszą przez etykiety. Nic nie zostaje przypadkowo wystawione na zewnątrz.
• TLS challenge — Traefik obsługuje weryfikację domeny bezpośrednio na porcie 443. Nie trzeba tymczasowo otwierać portu 80.
• acme.json — certyfikaty są zapisywane na dysku i przeżywają restarty kontenera. Przed pierwszym uruchomieniem utwórz plik i ustaw odpowiednie uprawnienia:

touch acme.json && chmod 600 acme.json

Traefik odmówi uruchomienia przy zbyt szerokich uprawnieniach.

• Zewnętrzna sieć web — tworzysz ją raz:

docker network create web

Każda usługa potrzebująca routingu HTTP/S dołącza do tej sieci.

Część 2 — Certyfikaty testowe (staging)#

Przed przejściem na produkcję przetestuj z serwerem staging Let's Encrypt, żeby nie trafić na limity:

# dodaj do sekcji command w traefik:
- "--log.level=DEBUG"
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Certyfikaty stagingowe nie są zaufane przez przeglądarki, ale funkcjonalnie działają identycznie. Usuń te linie gdy wszystko działa.

Część 3 — Dodanie usługi#

Tu widać zwrot z inwestycji. Dowolny kontener dostaje HTTPS przez dodanie czterech etykiet:

services:
    myapp:
        image: myapp:latest
        networks:
            - web
        labels:
            - traefik.enable=true
            - traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
            - traefik.http.routers.myapp.entrypoints=websecure
            - traefik.http.routers.myapp.tls.certresolver=le

networks:
    web:
        external: true

Traefik wykrywa kontener, pobiera certyfikat od Let's Encrypt i zaczyna routować ruch — bez konfiguracji nginx, bez uruchamiania certbota, bez crona. Odnowienia dzieją się automatycznie w tle.

Alternatywa bez Dockera#

Jeśli nie używasz Dockera, Certbot z wtyczką nginx to standardowe podejście: apt install certbot python3-certbot-nginx, certbot --nginx -d mojastrona.pl, a timer systemd zajmuje się odnowieniami. Sprawdza się dobrze na jednym serwerze z kilkoma stronami. Gdy usług jest więcej, podejście z Traefik zaczyna się opłacać.

Specyfikacja sprzętowa#

Nowy zestaw został skompletowany z myślą o maksymalnej responsywności i stabilności:

• Jednostka: Raspberry Pi 5 (8GB RAM).
• Obudowa: Argon NEO 5 M.2 NVMe – zapewnia skuteczne chłodzenie i bezpośrednią obsługę dysków SSD przez dedykowany interfejs.
• Pamięć masowa: Dysk Lexar 1TB M.2 PCIe NVMe NM620. Rezygnacja z kart micro SD na rzecz NVMe znacząco redukuje opóźnienia i zwiększa trwałość nośnika.

Energooszczędność#

Jednym z kluczowych argumentów za wyborem Raspberry Pi w roli serwera 24/7 jest niski pobór mocy. W obecnej konfiguracji parametry prezentują się następująco:

• Idle (bezczynność): Zapotrzebowanie na poziomie 3W (potwierdzone odczytem z zasilacza).
• Stress (obciążenie): Pobór mocy wzrasta do przedziału 9-12W.

Stosunek wydajności do zużytej energii czyni tę jednostkę niezwykle efektywnym rozwiązaniem pod kątem kosztów eksploatacji.

System i usługi systemowe#

Całość pracuje pod kontrolą Raspberry Pi OS. Na poziomie systemu operacyjnego (poza Dockerem) skonfigurowałem kluczowe usługi zarządzania i dostępu:

• Dostęp zdalny: VPN oparty na protokole Wireguard (PiVPN) zapewnia bezpieczny tunel do sieci domowej.
• Zarządzanie: Do obsługi graficznego interfejsu wykorzystuję VNC.
• Współdzielenie plików: Standardowa usługa Samba do szybkiego dostępu do danych w sieci lokalnej.

Środowisko Docker#

Kluczową zmianą w stosunku do poprzedniego serwera jest pełna konteneryzacja usług sieciowych. Za routing i automatyczne wystawianie certyfikatów SSL odpowiada Traefik.

W ramach Dockera utrzymuję obecnie:

1. holas.pl – moja strona internetowa.
2. Nextcloud – prywatna chmura do synchronizacji danych.
3. Immich – rozwiązanie do backupu i zarządzania biblioteką zdjęć.
4. Traefik – reverse proxy zarządzające ruchem przychodzącym.

Potencjał rozwojowy#

Mimo uruchomienia kilku wymagających usług, Raspberry Pi 5 w wersji 8GB wykazuje spory zapas mocy obliczeniowej oraz pamięci RAM. Obecne obciążenie pozwala na swobodne wdrażanie kolejnych kontenerów bez ryzyka spadku wydajności działających już systemów. Przejście na standard NVMe sprawiło, że operacje na bazach danych (szczególnie w Immich i Nextcloud) są wykonywane natychmiastowo.

Po roku użytkowania wewnętrznego wyszło v1.0.0 — z pełnym wsparciem dla Syliusa 2.x, czystą strukturą i wszystkim, czego używam na co dzień. Następnego dnia pojawiło się v1.0.1 z poprawkami dla różnych platform.

Dlaczego konfiguracja Syliusa bez narzędzi jest uciążliwa#

Sylius 2.x ma nietrywialną konfigurację lokalną. Wymaga PHP 8.4, Composera, bazy danych, serwera WWW z poprawnymi regułami rewrite, Node.js i Yarn do kompilacji assetów panelu admina (opartych na Webpack Encore) oraz binarki Symfony do zadań konsolowych. Sprawne uruchomienie tego wszystkiego na różnych maszynach — Windows, macOS, Linux — bez środowiska kontenerowego jest zawodne. Wersje się rozjeżdżają, zmienne środowiskowe różnią się, ścieżki kolidują.

DDEV rozwiązuje to, deklarując całe środowisko jako konfigurację. Boilerplate ma wbudowane właściwe wersje i łączy je razem, żeby nikt nie musiał tego rozgryzać ręcznie.

Co jest konfigurowane#

Plik .ddev/config.yaml ustawia:

• PHP 8.4 z apache-fpm (Sylius 2.x wymaga PHP 8.2+; 8.4 to obecna stabilna wersja)
• MariaDB 11.8 — najnowsza stabilna, z upload_dirs dostosowanym tak, żeby wykluczyć media/, node_modules/ i backups/ z synchronizacji Mutagen na macOS
• Composer 2
• Porty 8123 (HTTP) i 8443 (HTTPS), żeby unikać konfliktów z innymi lokalnymi projektami
• Xdebug wyłączony domyślnie — włączany przez ddev xdebug on gdy potrzebny

Co jest w środku#

ddev-sylius to szablon projektu oparty na DDEV dla Syliusa 2.x. Sklonuj, uruchom dwie komendy i masz działającą lokalną instancję Syliusa — bez ręcznej konfiguracji wersji PHP, bazy danych ani serwera WWW.

Niestandardowe komendy DDEV dołączone do boilerplate'u:

• ddev sylius-install — pełna instalacja Syliusa od zera
• ddev cc — czyszczenie cache
• ddev dist — instalacja zależności i budowanie assetów (Composer + Yarn)
• ddev yarn <param> — komendy Yarn wewnątrz kontenera
• ddev security-checker — skanowanie znanych podatności
• ddev code-check — weryfikacja standardów kodowania
• ddev backup / ddev database-import / ddev files-import — backup i przywracanie bazy danych i mediów
• ddev sylius-cleanup — resetowanie wszystkich danych (przydatne przy testowaniu przepływu instalacji)
• ddev build-site / ddev rebuild-site — pełna lub częściowa przebudowa projektu

Przetestowane na Windowsie 11 z WSL2 (Ubuntu 24.04), macOS Tahoe (Apple Silicon) i Linuksie z Dockerem.

Jak zacząć#

git clone https://github.com/holas1337/ddev-sylius my-projekt
cd my-projekt
ddev start
ddev sylius-install

Tyle. Po kilku minutach masz działający sklep Sylius z panelem administracyjnym, dostępny pod lokalnym URL-em wygenerowanym przez DDEV (domyślnie https://ddev-sylius-boilerplate.ddev.site:8443).

Codzienna praca#

Po pierwszej instalacji typowe komendy to:

ddev start             # start środowiska
ddev cc                # czyszczenie cache po zmianach konfiguracji
ddev dist              # przebudowa assetów po zmianach frontendu
ddev code-check        # sprawdzenie standardów przed commitem
ddev backup            # snapshot bazy przed ryzykowną migracją

Do debugowania ddev xdebug on włącza Xdebug, a ddev exec bin/console <komenda> daje bezpośredni dostęp do konsoli Symfony wewnątrz kontenera.

Co zmieniło się w v1.0.1#

Poprawka wydana następnego dnia naprawiła kilka rzeczy, które wyszły podczas testów na różnych platformach: dostosowania specyficzne dla macOS dla Mutagen i wyłączeń katalogów uploadu, aktualizacja MariaDB z 11.4 do 11.8 oraz aktualizacja phpMyAdmin do najnowszej wersji.

Repozytorium jest na GitHubie: holas1337/ddev-sylius. Issues i PR-y mile widziane.

uBlock Origin#

Niezbędna pierwsza warstwa ochrony. uBlock Origin (Firefox, Chrome) blokuje reklamy i śledzenie na poziomie sieciowym. Już z domyślnymi listami filtrów blokuje większość pikseli śledzących Facebooka i widżetów społecznościowych na stronach trzecich.

Uwaga dla użytkowników Chrome: Przejście Google na Manifest V3 ogranicza niektóre możliwości uBlock Origin w Chrome. Pełna wersja pozostaje dostępna w Firefoksie.

Privacy Badger#

Privacy Badger od Electronic Frontier Foundation (Firefox, Chrome) działa inaczej niż klasyczne blokery: zamiast statycznej listy blokowania, uczy się, które śledziki podążają za tobą między stronami i stopniowo je blokuje. Dobrze współpracuje z uBlock Origin.

Facebook Container (tylko Firefox)#

Facebook Container to rozszerzenie Mozilli, które izoluje sesję Facebooka w osobnej zakładce kontenera. Facebook nie widzi twojej aktywności na innych stronach, a widżety Facebooka na innych stronach nie mogą odczytać twoich ciasteczek sesji.

To najskuteczniejsze pojedyncze rozszerzenie wymierzone konkretnie w śledzenie Facebooka między stronami — stworzone i utrzymywane przez Mozillę.

Wbudowana ochrona przeglądarek#

Zarówno Firefox, jak i Brave mają domyślnie włączoną rozszerzoną ochronę przed śledzeniem, która blokuje wielu znanych śledzicieli — w tym Facebooka. Jeśli korzystasz z jednej z tych przeglądarek, masz już solidną bazę — rozszerzenia powyżej dodają do niej bardziej szczegółową kontrolę.

Jeśli używasz Chrome, rozważ przejście na Firefoksa dla lepszej domyślnej prywatności.

Przed Let's Encrypt uzyskanie zaufanego certyfikatu SSL wymagało płacenia komerycjnemu CA (Comodo, DigiCert, GoDaddy) od 200 do kilku tysięcy złotych rocznie, ręcznej weryfikacji tożsamości i samodzielnej obsługi odnowień. Let's Encrypt uruchomił się w 2015 roku, wyszedł z bety w kwietniu 2016 i zmienił to całkowicie: darmowe certyfikaty Domain Validation, automatyczne wydawanie przez protokół ACME, 90-dniowy czas ważności z wbudowaną obsługą odnowień. Dla małych serwerów i prywatnych stron działających dotychczas na HTTP była to pierwsza praktyczna droga do HTTPS.

Oficjalny klient Certbot nie był jeszcze dostępny w repozytoriach Debiana Jessie, więc skorzystałem z jednego z alternatywnych klientów — prostego skryptu bash: https://github.com/Neilpang/acme.sh

Używając tego skryptu można wszystko zrobić dosłownie w 5 minut.

Wymagania#

• Dostęp root do serwera
• Apache działający na Debianie Jessie
• Domena wskazująca na publiczne IP serwera
• Otwarty port 80 (używany przez challenge HTTP-01 do weryfikacji własności domeny)

Na wstępie ustalmy, że wszystko wykonujemy z roota oraz:

/root/.acme.sh/acme.sh     # miejsce składowania skryptów klienta
mojastrona.pl              # strona, dla której chcemy uzyskać certyfikat
/mnt/www/mojastrona.pl     # katalog na dysku naszej strony
/etc/apache2               # lokalizacja Apache wraz z plikami konfiguracji

Krok 1 — Pobierz klienta#

Przechodzimy do katalogu /root/.acme.sh/acme.sh (tworzymy jeśli nie istnieje) i wykonujemy:

git clone https://github.com/Neilpang/acme.sh

Jeśli nie mamy gita, pobieramy pliki ręcznie ze strony projektu i wypakowujemy.

Krok 2 — Symlink dla wygody#

ln -s /root/.acme.sh/ /etc/apache2/letsencrypt

Krok 3 — Pobierz certyfikat#

Upewniamy się, że strona jest dostępna z internetu, następnie:

./acme.sh issue /mnt/www/mojastrona.pl/ mojastrona.pl

Lub jeśli mamy aliasy (np. www.mojastrona.pl):

./acme.sh issue /mnt/www/mojastrona.pl/ mojastrona.pl www.mojastrona.pl

acme.sh umieszcza tymczasowy plik w webroocie, Let's Encrypt go pobiera, żeby zweryfikować że kontrolujesz domenę, i wydaje certyfikat. Pliki zapisane zostaną w:

/root/.acme.sh/mojastrona.pl/

Krok 4 — Konfiguracja Apache#

Wskazujemy Apache na nowe certyfikaty w pliku virtual hosta:

SSLCACertificateFile  /etc/apache2/letsencrypt/mojastrona.pl/ca.cer
SSLCertificateFile    /etc/apache2/letsencrypt/mojastrona.pl/mojastrona.pl.cer
SSLCertificateKeyFile /etc/apache2/letsencrypt/mojastrona.pl/mojastrona.pl.key

Następnie przeładowujemy Apache:

service apache2 reload

Od tego momentu strona powinna serwować certyfikat Let's Encrypt.

Krok 5 — Automatyczne odnawianie#

Certyfikaty mają ważność 90 dni. Aby odnawiać automatycznie, tworzymy wykonywalny skrypt acme_cron:

#!/bin/sh
/root/.acme.sh/acme.sh/acme.sh cron >> /var/log/le-renew.log
service apache2 reload

I przenosimy go do /etc/cron.daily.

Proces nie jest skomplikowany — po pierwszej konfiguracji odnawianie przebiega w pełni automatycznie.

Ta konfiguracja działała sprawnie, dopóki nie przeniosłem wszystkiego na Dockera. Nowoczesne podejście z Traefik obsługuje Let's Encrypt automatycznie — bez skryptów, bez crona, bez ręcznej konfiguracji. Więcej: Let's Encrypt z Dockerem i Traefik.

Jest prostsze wyjście: tymczasowe adresy e-mail — gotowe w kilka sekund, bez rejestracji, znikają po kilku godzinach.

Guerrilla Mail#

Guerrilla Mail to najprostszy wybór. Wchodzisz na stronę, kopiujesz wygenerowany adres, używasz go gdzie trzeba. Poczta pojawia się od razu — bez odświeżania. Skrzynka działa w ramach sesji przeglądarki: zamkniesz kartę i adres znika.

Możesz też wysyłać wiadomości z tymczasowego adresu — przydaje się przy niektórych formularzach potwierdzających.

Dropmail#

Dropmail oferuje więcej. To lepszy wybór, gdy adres ma przetrwać dłużej albo gdy zależy Ci na niezawodnym odbieraniu wiadomości.

Co wyróżnia Dropmail:

• Przekierowanie na prawdziwy adres — maile trafiają do Twojej normalnej skrzynki, nie musisz trzymać otwartej karty z Dropmail. Przekierowanie możesz anulować w każdej chwili.
• Klucz odzyskiwania — zapisz go i możesz wrócić do tego samego adresu później, nawet z innego urządzenia lub sesji przeglądarki
• Dwa typy domen — domeny stałe dla długotrwałych adresów, rotujące dla jednorazowego użytku
• Bot na Telegrama — odbieraj maile bezpośrednio w Telegramie bez otwierania przeglądarki
• Aplikacja na Androida — zarządzaj tymczasowymi adresami z telefonu

Żadna z powyższych funkcji nie wymaga rejestracji ani płatnego planu.

Apple Hide My Email#

Jeśli korzystasz z urządzeń Apple i masz subskrypcję iCloud+ (dostępną w każdym płatnym planie iCloud od 50 GB), masz już wbudowaną opcję: Hide My Email.

Generuje unikalny, losowy adres, który przekierowuje pocztę na Twoją prawdziwą skrzynkę — na stałe, dopóki go nie dezaktywujesz. Żadnej osobnej aplikacji, żadnej strony do odwiedzania. Funkcja jest wbudowana bezpośrednio w iOS, iPadOS i macOS:

• Autouzupełnianie w Safari — gdy wypełniasz pole e-mail na stronie, Safari proponuje automatyczne wygenerowanie ukrytego adresu
• Ustawienia → iCloud → Hide My Email — twórz adresy i zarządzaj nimi w jednym miejscu, sprawdzaj które są aktywne, dezaktywuj lub usuń dowolny z nich
• Zaloguj się przez Apple — gdy wybierasz opcję ukrycia adresu przy logowaniu przez Apple, Hide My Email generuje adres automatycznie

Kluczowa różnica w stosunku do Guerrilla Mail i Dropmail: te adresy to stałe aliasy powiązane z Twoim Apple ID, nie jednorazowe skrzynki. Ty nimi zarządzasz, możesz je wyłączyć, a poczta zawsze trafia do Twojej prawdziwej skrzynki. To najbardziej bezproblemowa opcja jeśli jesteś w ekosystemie Apple — zero dodatkowych narzędzi, stałe i zarządzalne aliasy.

Ograniczenie: wymaga płatnego planu iCloud+ i działa tylko na urządzeniach Apple.

Kiedy używać którego#

Używaj Guerrilla Mail gdy potrzebujesz tylko linku potwierdzającego i za dwie minuty zamkniesz kartę.

Używaj Dropmail gdy adres ma przeżyć zamknięcie przeglądarki albo gdy chcesz, żeby maile trafiały w miejsce, gdzie je faktycznie zobaczysz.

Używaj Apple Hide My Email gdy jesteś na iPhonie lub Macu, masz iCloud+, i chcesz generować adresy bez żadnego dodatkowego narzędzia — wbudowane w system, stałe i zarządzalne aliasy.

Co serwis miał robić#

Pośrednictwo ubezpieczeniowe to branża regulowana. Strona brokera to nie tylko broszura — musi komunikować status regulacyjny (numer licencji KNF, ubezpieczenie OC zawodowe), odróżniać firmę od agentów (broker reprezentuje klienta, nie ubezpieczyciela) i budować wystarczające zaufanie, żeby potencjalny klient korporacyjny zadzwonił.

Portfolio usług Alfa Consilium było szerokie: ubezpieczenia D&O, cargo, OC spedytora i OC przewoźnika, ubezpieczenia maszyn, brokerstwo leasingowe, faktoring, zarządzanie wierzytelnościami i zarządzanie ryzykiem z wizytami audytowymi na miejscu. Każdy obszar usług wymagał czytelnego, samodzielnego opisu — nie ściany tekstu, ale treści wystarczającej, żeby decydent zrozumiał zakres i skontaktował się z zespołem.

Projekt i wdrożenie#

Serwis został zaprojektowany w czystej estetyce korporacyjnej: ustrukturyzowany układ, czytelna nawigacja po usługach i dane kontaktowe dostępne z każdej podstrony. Klienci z sektora finansowego — firmy logistyczne, produkcyjne, floty — oczekują profesjonalnej prezentacji, nie startupowej landing page.

Wdrożenie na WordPressie z autorskim motywem PHP pisanym od podstaw — bez gotowego szablonu. Szablon obsługiwał trzy breakpointy responsywne: komputer, tablet i telefon. Responsywny design w 2016 roku wciąż nie był standardem dla małych polskich serwisów korporacyjnych; większość działała na stałej szerokości.

WordPress był właściwym wyborem dla klienta: zespół mógł aktualizować opisy usług i aktualności bez udziału dewelopera, a panel administracyjny nie wymagał żadnego szkolenia.

Co zostało dostarczone#

• Pełny projekt graficzny (desktop + tablet + mobile)
• Autorski motyw WordPress w PHP
• Podstrony usług dla wszystkich linii ubezpieczeniowych i finansowych
• Sekcja kontaktowa z informacjami regulacyjnymi (dane nadzoru KNF, OC zawodowe)
• Responsywny układ na wszystkich trzech breakpointach

Zrzut ekranu z działającego serwisu.

Firma działa nadal — pierwotna domena .pl przekierowuje teraz na alfaconsilium.eu.