Część 4 wyjaśniła jak wzorzec nadpisywania local/ działa w teorii — priorytet przestrzeni nazw Twig, kolejność kaskady SCSS i model łączenia w czasie budowy. Ten post buduje z nim prawdziwy motyw, od początku do końca. Nie zabawkowy przykład. Produkcyjny motyw z własnymi komponentami, responsywnymi obrazami, paskiem bocznym i wyszukiwarką.

Punkty startowe — szablony#

Katalog docs/customization/ zawiera sześć zestawów szablonów, każdy demonstrujący jeden wzorzec nadpisywania:

Zaczniemy od material-cards i rozbudujemy w pełny motyw.

Krok 1: Przygotowanie bazy#

Kopiujemy szablon do local/:

cp -r docs/customization/starter-extend/. local/

Szablon zawiera dwa pliki. Pierwszy, local/templates/base.html.twig — minimalne nadpisanie bazy:

{% extends '@base/base.html.twig' %}

{% block stylesheets %}
    {{ importmap('app') }}
    {{ importmap('app-local') }}
{% endblock %}

Prefiks @base/ jawnie przypina do rdzennych szablonów. Bez niego extends 'base.html.twig' szukałoby najpierw w local/ — tworząc cykliczną referencję gdzie local rozszerza samego siebie. Blok stylesheets dodaje punkt wejścia app-local obok rdzennego app.

Drugi, local/assets/app.js — lokalny punkt wejścia JS:

import './styles/app_local.scss';

Ten plik sprawia że app-local pojawia się w importmap.php. Jego jedynym zadaniem jest importowanie lokalnego SCSS. Wszelkie dodatkowe importy JS też trafiają tutaj.

Krok 2: Nadpisanie tokenów SCSS#

Tożsamość wizualna motywu żyje w dwóch plikach: local/assets/styles/_tokens.scss (własności CSS) i local/assets/styles/_variables.scss (stałe SCSS).

Motyw demo używa ciemnej palety bursztynowo-fosforowej. Oto co autor motywu zmienia w _tokens.scss:

:root {
    --bg: #171717;           /* prawie czarne tło strony */
    --bg-sidebar: #0f0f0f;   /* jeszcze ciemniejszy sidebar */
    --text: #e8e8e8;         /* jasnoszary tekst */
    --text-muted: #8c8c8c;   /* przygaszony tekst drugorzędny */
    --accent: #f59e0b;       /* bursztynowy kolor wyróżnienia */
    --border: #404040;       /* widoczny ale nie krzykliwy */
    --code-bg: #1c1c1c;      /* tło bloków kodu */
}

A w _variables.scss:

$font: 'Inter', ui-sans-serif, system-ui, sans-serif;
$font-mono: 'JetBrains Mono', ui-monospace, monospace;
$radius-sm: 4px;
$radius: 6px;
$radius-md: 8px;

Wszystko inne w kaskadzie — _base.scss, _components.scss, _prose.scss — używa tych zmiennych. Zmień --accent a każdy przycisk, link, odznaka i pierścień focus się aktualizuje. Żaden SCSS komponentu nietknięty.

Krok 3: Nadpisanie bloków Twig#

base.html.twig definiuje około 20 regionów {% block %}. Te które faktycznie będziesz nadpisywać:

stylesheets — zrobione w kroku 1. Dodaje importmapę app-local.

favicons — własne ścieżki ikon:

{% block favicons %}
    <link rel="icon" href="{{ asset('local/favicon.svg') }}" type="image/svg+xml">
    <link rel="apple-touch-icon" href="{{ asset('local/apple-touch-icon.png') }}">
{% endblock %}

Lokalne assety używają prefiksu ścieżki local/ bo asset_mapper.yaml mapuje local/assets/: local.

navigation — zastępuje cały include nawigacji:

{% block navigation %}
    {{ include('components/navigation.html.twig') }}
{% endblock %}

Deleguje do lokalnego nadpisania komponentu — to samo wywołanie include ale rozwiązuje się najpierw do local/templates/components/navigation.html.twig.

sidebar_top i sidebar_bottom — własna zawartość widgetów:

{% block sidebar_top %}
    <div class="widget widget-cta">
        <h3>Współpraca</h3>
        <p>Buduję niestandardowe aplikacje Symfony i statyczne strony.</p>
        <a href="{{ path('contact_' ~ locale) }}" class="btn btn-primary">Skontaktuj się</a>
    </div>
{% endblock %}

footer — nie jest blokiem w rdzeniu. Stopka to zakodowany HTML w base.html.twig. Żeby ją dostosować, musisz zastąpić cały base.html.twig pełną kopią. To jedyna część systemu która wymaga pełnego nadpisania szablonu. Alternatywą jest dodanie własnego bloku Twig w lokalnym nadpisaniu bazy i aktualizacja wszystkich szablonów stron by go używały, ale pełna zamiana jest prostsza w większości przypadków.

Krok 4: Nadpisanie szablonów komponentów#

Serce tworzenia motywu. Kopiuj komponent z templates/components/ do local/templates/components/ i edytuj:

cp templates/components/post_card.html.twig local/templates/components/post_card.html.twig

Wywołanie include się nie zmienia:

{{ include('components/post_card.html.twig') }}

Rozwiązywanie szablonów szuka najpierw w local/templates/ (główna przestrzeń nazw ''), potem przepada do templates/ (rdzeń). Wywołujący nie wie i nie dba który plik jest użyty.

Sześć komponentów które będziesz najczęściej nadpisywać:

post_card.html.twig — główna karta wpisu. Otrzymywane zmienne: post (ContentItem), featured (bool), locale (string), new_post_days (int). Lokalne nadpisanie może dodać układ poziomy, przesunąć obraz na prawo lub zmienić kolejność meta-linii.

post_card_mini.html.twig — kompaktowa karta dla ostatnich wpisów w sidebarze i powiązanych wpisów. Te same zmienne, mniejszy markup, bez obrazu.

navigation.html.twig — główna nawigacja z linkami i przełącznikiem języków. Zmienne: locale, dostęp do funkcji content_item() i path() Twig. Lokalne nadpisanie dodaje, usuwa lub zmienia kolejność elementów nawigacji.

sidebar_top.html.twig — widget formularza wyszukiwania. Zmienne: sidebar (obiekt wartości SidebarData). Lokalne nadpisanie zastępuje formularz wyszukiwania widgetem CTA lub własną treścią.

sidebar_bottom.html.twig — widgety ostatnich wpisów, kategorii, tagów. Zmienne: sidebar, locale, filter_type, filter_value. Lokalne nadpisanie zmienia prezentację filtrów lub ogranicza liczbę ostatnich wpisów.

breadcrumb.html.twig — ścieżka nawigacyjna. Zmienne: breadcrumbs (tablica z funkcji Twig breadcrumbs()). Lokalne nadpisanie zmienia separator z / na → lub restrukturyzuje markup.

pagination.html.twig — linki poprzedniej/następnej strony. Zmienne: current_page, total_pages, base_url, paginated_route. Lokalne nadpisanie stylizuje kontener paginacji.

Krok 5: Tworzenie własnych komponentów#

Wyodrębnij powtarzające się wzorce UI do nowych plików w local/templates/components/:

local/templates/components/hero_banner.html.twig:

<section class="hero-banner">
    <h1>{{ title }}</h1>
    {% if subtitle is defined %}
        <p class="hero-banner__subtitle">{{ subtitle }}</p>
    {% endif %}
</section>

Załączony w szablonie strony głównej:

{% block body %}
    {{ include('components/hero_banner.html.twig', {
        title: site_name,
        subtitle: site_description
    }) }}
{% endblock %}

Komponenty otrzymują zmienne z kontekstu szablonu wywołującego — bez specjalnej rejestracji, bez manifestu, bez konfiguracji autoloadingu. Po prostu plik Twig w odpowiednim katalogu.

Krok 6: Dodanie lokalnego JavaScript#

Punkt wejścia app-local importuje dodatkowe zachowania:

// local/assets/app.js
import './styles/app_local.scss';
import './js/theme-toggle.js';
import './js/scroll-animations.js';

Pliki JS żyją w local/assets/js/ i są kompilowane do public/assets/local/ przez asset-map:compile. Są dostępne w szablonach przez:

<script src="{{ asset('local/js/theme-toggle.js') }}" defer></script>

Kontrolery Stimulus auto-wykrywane z local/assets/controllers/ działają zgodnie z konwencją Symfony — po prostu umieść tam plik *_controller.js i odwołuj się atrybutami data-controller w markupie.

Krok 7: Dodanie własnych funkcji i filtrów Twig#

Umieść pliki PHP w local/src/ pod przestrzenią nazw NotACms\Local\:

<?php

declare(strict_types=1);

namespace NotACms\Local\Twig;

use Symfony\Bridge\Twig\Attribute\AsTwigFilter;
use Twig\Extension\AbstractExtension;

final class ReadingTimeExtension extends AbstractExtension
{
    #[AsTwigFilter('reading_time')]
    public function readingTime(string $html, int $wordsPerMinute = 200): string
    {
        $wordCount = str_word_count(strip_tags($html));

        return (string) max(1, (int) ceil($wordCount / $wordsPerMinute));
    }
}

Zero ręcznej rejestracji serwisów. Plik services.yaml już skanuje local/src/:

services:
    NotACms\Local\:
        resource: '../local/src/'

Symfony auto-wykrywa klasy z atrybutami #[AsTwigFilter], #[AsTwigFunction] lub #[AsTwigExtension]. Użyj atrybutu, umieść plik w local/src/, a funkcja jest dostępna we wszystkich szablonach.

Krok 8: Dekoracja serwisu#

Zmień zachowanie rdzenia bez modyfikowania rdzennego kodu. Umieść klasę dekoratora w local/src/Service/:

<?php

declare(strict_types=1);

namespace NotACms\Local\Service;

use NotACms\Service\Turnstile\TurnstileValidatorInterface;
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;

#[AsDecorator(decorates: TurnstileValidatorInterface::class)]
final readonly class TurnstileSkipDecorator implements TurnstileValidatorInterface
{
    public function verify(string $token, ?string $remoteIp = null): bool
    {
        return true;
    }
}

Atrybut #[AsDecorator] mówi Symfony by opakowało prawdziwy TurnstileValidator tym dekoratorem. Cały kod type-hintujący TurnstileValidatorInterface otrzymuje teraz dekorator — który całkowicie pomija weryfikację. Przydatne w lokalnym dev gdzie Cloudflare Turnstile nie może się połączyć z localhost. Usuń plik na produkcji, a prawdziwy walidator przejmuje kontrolę.

Krok 9: Testowanie motywu#

Uruchom ddev build i sprawdź każdy typ strony:

1. Strona główna — hero banner, karty wpisów, sekcja CTA
2. Lista wpisów — paginacja, linki filtrów, układ kart
3. Pojedynczy wpis — obraz wyróżniający, pasek postępu czytania, tagi, nawigacja serii, powiązane wpisy
4. Strona kategorii — filtrowana lista z nagłówkiem kategorii
5. Strona tagu — filtrowana lista z nagłówkiem tagu
6. Miesiąc/rok archiwum — lista archiwalna z nagłówkiem daty
7. Strony statyczne — o mnie, kontakt, realizacje, polityka prywatności
8. Strona wyszukiwarki — wyniki Pagefind z własnym stylowaniem
9. Strony błędów — 404 i 500 ze stylowaniem motywu
10. Styleguide — /styleguide/ pokazujący wszystkie komponenty w izolacji

Strona styleguide to najcenniejsze narzędzie debugowania. Zaktualizuj local/templates/page/styleguide.html.twig by zawierał nowe własne komponenty. Uruchom build, otwórz styleguide, a każdy komponent — rdzenny i własny — jest widoczny na jednej stronie z przykładowymi danymi.

Sprawdź breakpointy responsywne na mobile (375px), tablecie (768px) i desktopie (1280px). Zweryfikuj że fingerprinting assetów wygenerował nowe hashe w public/assets/ — jeśli hashe zgadzają się z poprzednim buildem, SCSS motywu się nie zmienił.

Mechanizm rozwiązywania szablonów#

Zrozumienie jak dokładnie Twig rozwiązuje szablony zapobiega cichym błędom:

include('components/post_card.html.twig')
  1. local/templates/components/post_card.html.twig  ← główna przestrzeń '' (pierwsza)
  2. templates/components/post_card.html.twig          ← rdzeń (fallback)

extends '@base/base.html.twig'   ← jawnie przypięte do rdzenia, nigdy local
extends 'base.html.twig'         ← szuka najpierw local, potem rdzeń

Konfiguracja która to umożliwia, z config/packages/twig.yaml:

twig:
    paths:
        '%kernel.project_dir%/local/templates': ''    # główna przestrzeń — najwyższy priorytet
        '%kernel.project_dir%/templates': 'base'       # przestrzeń @base — cel jawnego przypięcia

Główna przestrzeń nazw ('') zawsze ma priorytet. Rdzenne szablony są osiągalne przez @base/ gdy potrzebne jest jawne przypięcie. Lokalne szablony które chcą rozszerzać z rdzenia używają {% extends '@base/base.html.twig' %} — to nigdy się nie zmienia, nawet jeśli lokalny base.html.twig też istnieje.

Strategia kaskady SCSS#

Dwa punkty wejścia importmap tworzą kaskadę bez !important:

Przeglądarka ładuje:
  1. public/assets/app-{h1}.css   ← kaskada rdzenia (tokens → variables → components → ...)
  2. public/assets/local/app-{h2}.css ← kaskada lokalna (tokens → variables → własne komponenty)

Wynik:
  Lokalne reguły ładują się po rdzennych.
  Przy równej specyficzności, lokalne wygrywają.
  Nigdzie !important.

To ten sam mechanizm który wzorzec local/ opisał w części 4, teraz zastosowany do prawdziwej budowy motywu. Rozdzielenie odpowiedzialności jest czyste: rdzeń dostarcza bazowe style przez zmienne, local nadpisuje te zmienne i dodaje własne style komponentów. Kaskada robi resztę.

Porównanie do innych podejść#

Motywy notACMS to po prostu Twig i SCSS. Bez specjalnego formatu, bez manifestu motywu, bez rejestracji. Cały "system motywów" to dwie linijki w twig.yaml i warunkowy wpis w importmap.php. Kopiuj plik, edytuj, buduj.

Część 8 zagłębia się w warstwę wyszukiwania: indeksowanie WASM Pagefind, dwa interfejsy wyszukiwania (samodzielna strona i nakładka Cmd+K), wdrożenie produkcyjne na ARM64 i czego Pagefind nie potrafi.

Polecenie ddev build tworzy kompletną statyczną stronę w mniej niż minutę. Ale co właściwie się dzieje? 10 odrębnych etapów, każdy to decyzja projektowa. Oto pełny pipeline — każde polecenie, każdy plik konfiguracyjny, każdy wybór architektoniczny.

10-etapowy pipeline#

Etap 1: Zainicjowanie local/#

Zanim cokolwiek się skompiluje, build upewnia się że istnieje działający katalog local/. Jeśli jest pusty lub nie istnieje, build kopiuje do niego docs/demo/:

cp -r docs/demo/. local/

Jeśli local/ ma już prawdziwą zawartość, build pomija ten krok. Flaga --bare inicjuje z docs/bare/ — minimalnego szkieletu bez treści, przydatnego przy zaczynaniu od zera. Flaga --demo wymusza ponowną inicjalizację nawet jeśli treść istnieje, tworząc kopię zapasową starego local/ jako local-{TIMESTAMP}/.

Build kopiuje też assets/images/og-default.jpg do local/assets/images/ jeśli go brakuje — zapasowy obraz Open Graph, gdy strona nie ma własnego.

Etap 2: Instalacja Composera#

composer install --optimize-autoloader --no-interaction

Standardowy krok Symfony. Flaga --optimize-autoloader tworzy classmapę dla szybszego autoloadingu — istotne, bo każde pod-żądanie w buildzie tworzy nowy kontener serwisów.

Etap 3: Wyczyszczenie dart-sass#

rm -rf var/dart-sass

Polecenie sass:build pobiera binarkę dart-sass specyficzną dla architektury. Wyczyszczenie przed każdym buildem zapewnia poprawną binarkę dla bieżącej platformy. Kluczowe dla przepływów międzyplatformowych — development na ARM64 (Raspberry Pi 5), CI/CD na x86_64 (GitHub Actions), deployment znów na ARM64.

Etap 4: Wyczyszczenie cache#

php bin/console cache:clear

Tworzy skompilowany kontener wstrzykiwania zależności Symfony. Ciepły cache poprawia wydajność pod-żądań podczas budowania statycznego.

Etap 5: Kompilacja SCSS#

php bin/console sass:build

Kompiluje assets/styles/app.scss do var/sass/app.css. Kaskada importów rdzennego SCSS, w kolejności:

_tokens.scss    ← CSS custom properties (--bg, --text, --accent, ...)
_variables.scss ← stałe SCSS czasu kompilacji ($font, $sp-*, $radius-*, ...)
_base.scss      ← reset, box-sizing, domyślne style body
_layout.scss    ← .container, .content-layout, .site-header/footer
_nav.scss       ← nawigacja, hamburger, dropdown, .skip-link
_components.scss ← post-card, paginacja, odznaki, przyciski, alerty, widgety
_prose.scss     ← klasa .prose dla wyrenderowanego Markdowna
_pages.scss     ← sekcje strony głównej, hero, CTA
_blog.scss      ← pasek postępu czytania, przycisk kopiowania kodu
_styleguide.scss ← klasy szkieletowe sg-*
_utilities.scss ← atomowe klasy narzędziowe

Lokalne motywy nadpisują _tokens.scss i _variables.scss — wszystko inne dziedziczy nowe wartości przez kaskadę. Zmień --accent z #2563EB na #FFA040, a każdy komponent, przycisk i link się aktualizuje bez dotykania SCSS komponentów.

Etap 6: Asset-map compile#

rm -rf public/assets
php bin/console asset-map:compile

Najpierw czyści wcześniej skompilowane assety, potem kompiluje wszystko zmapowane przez Symfony AssetMapper:

• assets/app.js → public/assets/app-{contenthash}.js
• var/sass/app.css → public/assets/app-{contenthash}.css
• local/assets/**/* → public/assets/local/**/* (jeśli local/assets/ istnieje)

{contenthash} to fingerprint pochodzący z zawartości pliku. Zmiana jednego znaku w SCSS generuje zupełnie inny hash, automatycznie unieważniając cache CDN i przeglądarki. Bez parametrów wersji w query stringu — sama nazwa pliku jest wersją.

Po kompilacji paczka sensiolabs_minify minifikuje wszystkie pliki CSS i JS. Plik importmap.php definiuje które punkty wejścia istnieją:

return array_filter([
    'app' => [
        'path' => './assets/app.js',
        'entrypoint' => true,
    ],
    'app-local' => file_exists(__DIR__ . '/local/assets/app.js')
        ? [
            'path' => './local/assets/app.js',
            'entrypoint' => true,
          ]
        : null,
]);

Dwa punkty wejścia: app (zawsze — rdzenny CSS + JS) i app-local (warunkowy — tylko jeśli local/assets/app.js istnieje). Oba są entrypoint: true, więc {{ importmap('app') }} i {{ importmap('app-local') }} w Twigu ładują je niezależnie. app-local ładuje się po app w szablonie, dając lokalnemu CSS ostatnie słowo w przypadku równej specyficzności bez !important.

Etap 7: Budowa statycznego HTML#

php bin/console app:build -v

To jest sedno magii. Flaga -v włącza szczegółowe wyjście, pokazujące każdy wyrenderowany URL. Pięć pod-etapów wykonuje się sekwencyjnie:

7a. Unieważnienie cache treści

Build czyści pulę cache app.content dla każdego skonfigurowanego locale. Cache przechowuje sparsowane obiekty ContentTree — unieważnienie wymusza pełne ponowne parsowanie wszystkich plików Markdown, zapewniając że statyczny build odzwierciedla bieżący stan treści. W developmentcie cache używa adaptera tablicowego w pamięci. W produkcyjnych buildach używa adaptera systemu plików w var/cache/.

7b. Zebranie tras

Metoda collectRoutes() zbiera każdy URL który serwuje strona. Dla każdego locale:

• Strona główna (home_{locale})
• Lista wpisów (blog_list_{locale})
• Paginowane strony listy (strony 2 do ceil(liczbaPostów / postówNaStronę))
• URL każdego opublikowanego wpisu (`$post->url()``)
• URL każdego zaplanowanego wpisu (renderuje stronę „wkrótce" z noindex)
• Każda strona kategorii (blog_category_{locale})
• Każda strona tagu (blog_tag_{locale})
• Każdy miesiąc archiwum (blog_archive_{locale} z parametrami rok + miesiąc)
• Każdy rok archiwum (blog_archive_year_{locale} — osobna trasa od miesięcy)
• Każda strona statyczna (nie-dynamiczna, niepusty URL, nie strona główna)
• Strona wyszukiwarki (search_{locale})

Wynik jest deduplikowany przez array_unique(). Dla strony z 4 locale i ~40 elementami treści na locale, daje to około 500 URL-i, uwzględniając paginację, archiwa, tagi i feedy.

7c. Renderowanie stron

Każdy URL jest renderowany przez pod-żądanie Symfony:

$request = Request::create($url, Request::METHOD_GET);
$request->attributes->set('_static_build', true);

$response = $this->httpKernel->handle(
    $request,
    HttpKernelInterface::SUB_REQUEST,
    false,
);

Atrybut _static_build sygnalizuje kontrolerom, serwisom i szablonom, że działają wewnątrz builda, a nie obsługują prawdziwego żądania HTTP. Motywy i lokalne rozszerzenia mogą na jego podstawie różnicować output między serwowaniem na żywo a buildem statycznym. (O widoczności szkiców/zaplanowanych wpisów decyduje natomiast brak deweloperskich przełączników podglądu w sesji — CLI nie ma sesji, więc build zawsze renderuje widok opublikowany.)

Ciało odpowiedzi jest zapisywane na dysk jako {katalogWyjściowy}/{url}/index.html. Główny URL / staje się index.html w katalogu wyjściowym. Każdy URL zwracający HTTP 400 lub więcej jest łapany jako błąd i pomijany (strona jest liczona jako pominięta, ale build kontynuuje).

Po wyrenderowaniu wszystkich stron z treścią, build renderuje URLe feedów:

• robots_{locale} — zapisywany jako {katalogWyjściowy}/robots.txt
• sitemap_{locale} — zapisywany jako {katalogWyjściowy}/sitemap.xml (lub index.xml dla URL-i zakończonych ukośnikiem)
• rss_{locale} — zapisywany jako {katalogWyjściowy}/rss.xml (lub index.xml)

Następnie strony błędów są renderowane przez pod-żądanie:

• error_404_{locale} → {prefiks}404.html
• error_500_{locale} → {prefiks}500.html

Gdzie {prefiks} to ścieżka locale innego niż domyślny (np. pl/404.html). Są one wstępnie renderowane, żeby nginx mógł je serwować bezpośrednio, bez wybudzania PHP-FPM.

Podejście z pod-żądaniem ma znaczenie dla poprawności: te same kontrolery i szablony Twig używane w trybie deweloperskim tworzą statyczne wyjście. To co widzisz w ddev start ląduje na produkcji. Bez osobnej ścieżki renderowania. Bez rozbieżności szablonów między trybem dev a build.

7d. Kopiowanie plików mediów

Symfony Finder lokalizuje każdy katalog files/ w drzewie treści i mirroruje je do wyjścia:

{katalogTreści}/{katalogWpisu}/files/  →  {katalogWyjściowy}/media/{katalogWpisu}/

To lustrzane kopiowanie brute-force — bez hashowania, bez deduplikacji, bez tree-shakingu. Autorzy treści kontrolują co jest w files/. Usuń stamtąd plik, znika z kolejnego builda. Prostota jest zamierzona: bez grafu assetów, bez manifestu builda, bez zliczania referencji.

7e. Optymalizacja oryginałów i generowanie wariantów responsywnych

Dwa przebiegi ImageMagick na zduplikowanym katalogu mediów:

Optymalizacja każdego pliku .webp (z pominięciem istniejących wariantów identyfikowanych przez wzorzec sufiksu -{szerokość}w):

$this->imageResizer->optimize($path);
// → exec('magick convert input.webp -quality 82 -strip -define webp:method=6 output.webp')

Jakość domyślnie 82, konfigurowalna w _site.yaml. Flaga -strip usuwa metadane (EXIF, profile ICC). Flaga webp:method=6 używa najwolniejszego ale najwydajniejszego enkodera WebP.

Generowanie wariantów responsywnych dla każdego oryginału .webp:

$width = getimagesize($path)[0];
$variantWidths = $this->responsiveImageService->getVariantWidths($width);
// [640, 960] przefiltrowane z konfiguracji — tylko szerokości < źródłowa

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

Dla obrazu źródłowego 1280px z skonfigurowanymi szerokościami wariantów [640, 960], produkuje to image-640w.webp i image-960w.webp. Oryginalny image.webp służy jako fallback 1280w.

Etap 8: Kopiowanie favicon#

cp local/assets/favicon.ico public/

Jeśli local/assets/favicon.ico nie istnieje, sięga po assets/images/favicon.ico z rdzenia. Blok favicons w base.html.twig można nadpisać w lokalnych szablonach by wskazywać inne ścieżki ikon.

Etap 9: Indeks Pagefind#

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

Pagefind skanuje wstępnie wyrenderowany HTML w poszukiwaniu regionów data-pagefind-body, buduje per-językowe binarne indeksy wyszukiwania WASM i zapisuje ~437 plików w public/pagefind/. Ten krok działa osobno od builda PHP, bo wymaga Node.js. Warstwa PHP nie ma zależności od Node — trzymanie Pagefind jako osobnego kroku orkiestracji oznacza że cała aplikacja PHP działa bez node_modules.

Skrypt produkcyjnego deployu (scripts/rebuild-content.sh) przypina Pagefind do wersji @1.5.0:

docker compose run --rm php npx --yes pagefind@1.5.0 --site public/static --output-path public/pagefind

Późniejsze wersje Pagefind dostarczają binarkę ARM64 linkowaną z jemalloc, która crashuje na hostach z jądrem używającym 16K stron (Raspberry Pi 5). Błąd: "<jemalloc>: Unsupported system page size". Przypięcie do 1.5.0 omija ten problem. DDEV-lokalny skrypt build nie przypina — działa na x86_64 gdzie wszystkie wersje są poprawne.

Etap 10: nginx serwuje#

Po wszystkich krokach public/ zawiera trzy katalogi:

public/
├── assets/        ← zfingerprintowane JS/CSS (immutable, długi cache)
├── static/        ← cały HTML + RSS + sitemap + media/
└── pagefind/      ← indeks wyszukiwarki (WASM + metadane)

Nginx try_files rozwiązuje każde przychodzące żądanie do wstępnie wyrenderowanego pliku:

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

PHP-FPM jest wołane tylko dla endpointa formularza kontaktowego:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass php:9000;
}

Cała strona poza formularzem kontaktowym to statyczne pliki na dysku. Bez runtime PHP. Bez bazy danych. Bez serwera aplikacji.

Podsumowanie pipeline'u#

Decyzje projektowe#

Dlaczego pod-żądania?#

Pod-żądania ponownie wykorzystują te same kontrolery i szablony Twig używane w trybie deweloperskim. Bez osobnej ścieżki renderowania. To co widzisz w ddev start trafia na produkcję. Atrybut _static_build to jedyny sygnał który się różni — cała reszta działa identycznie. Eliminuje to najczęstszy błąd statycznych generatorów: tryb dev renderujący inaczej niż output builda.

Dlaczego osobne etapy SCSS i asset-map?#

sass:build produkuje surowe CSS — przydatne w trybie deweloperskim watch, gdzie rekompilujesz przy zmianach plików ale nie chcesz re-fingerprintować przy każdym zapisie. asset-map:compile fingerprintuje i minifikuje — zmartwienie wyłącznie produkcyjne. Rozdzielenie oznacza że te dwie odpowiedzialności pozostają niezależne.

Dlaczego brute-copy mediów?#

Autorzy treści kontrolują co jest w files/. Bez manifestu builda. Bez tree-shakingu. Bez grafu assetów. Usuń z files/, znika z builda. Prostota jest warta miejsca na dysku — a miejsce na dysku dla obrazów WebP na statycznej stronie jest trywialne.

Dlaczego ImageMagick CLI, nie GD lub Imagick?#

exec('magick convert ...')

GD nie radzi sobie niezawodnie ze wszystkimi wariantami WebP (bezstratny, animowany, alfa). Imagick ma problemy z kompatybilnością rozszerzeń między wersjami PHP. ImageMagick CLI jest zawsze dostępny w kontenerze Dockera i jest najbardziej przenośną opcją między architekturami.

Dlaczego Pagefind jako osobny krok?#

Zależność od Node.js. Build PHP nie potrzebuje Node do niczego innego. Trzymanie Pagefind jako osobnego kroku orkiestracji oznacza że cała warstwa PHP działa bez node_modules — znaczące uproszczenie dla deploymentu i setupu deweloperskiego.

Wydajność#

Pełny pipeline wykonuje się w mniej niż 60 sekund dla strony o ~170 podstronach (4 locale, ~40 elementów treści na locale). Wąskie gardła:

• ImageMagick — 100+ optymalizacji obrazów i generowania wariantów. Obecnie sekwencyjne — jednowątkowa pętla PHP przez każdy plik. Zrównoleglenie (wiele exec() jednocześnie) byłoby największą pojedynczą poprawą.
• Renderowanie pod-żądań — ~1ms na żądanie, ~500 łącznie z paginacją. Skompilowany kontener Symfony sprawia że to szybkie. Główny koszt to kompilacja szablonów Twig, nie I/O.
• Pagefind — 2–5 sekund, zdominowane przez kompilację WASM z kodu źródłowego Rust, nie parsowanie HTML. Skaluje się liniowo z liczbą stron.

Punkty dostosowywania#

Pipeline ma pięć celowych punktów wstrzykiwania dla lokalnych nadpisań:

• local/assets/styles/ — nadpisuj częściowe pliki SCSS (_tokens.scss, _variables.scss)
• local/assets/ — dodawaj własny JS (staje się punktem wejścia app-local gdy app.js istnieje)
• local/templates/ — nadpisuj dowolny szablon Twig (przepada do rdzenia przez priorytet przestrzeni nazw)
• local/content/_site.yaml — zmieniaj szerokości wariantów, jakość obrazów, flagi Magick, liczbę postów na stronę
• local/src/ — dodawaj własne rozszerzenia Twig lub dekoratory serwisów (auto-wykrywane przez Symfony)

Zero plików konfiguracyjnych do edycji. Zero kroku rejestracji. Zero systemu wtyczek frameworka. Kopiuj plik do local/, edytuj, buduj. To cały model.

Część 7 opisuje budowę kompletnego motywu produkcyjnego na tym pipeline — bloki Twig, tokeny SCSS, własne komponenty, lokalny JS i dekorację serwisów. Część 8 zagłębia się w Pagefind: dwa interfejsy wyszukiwania, kontrakt data-pagefind-*, deployment produkcyjny i wojenna opowieść o przypinaniu wersji na ARM64.

Spędziłem miesiąc przygotowując kod mojej osobistej strony do wydania jako open-source. Nie dlatego że spodziewałem się tysięcy kontrybutorów — ale dlatego że publiczne udostępnienie zmusiło mnie do napisania dokumentacji, dodania testów, naprawy luk bezpieczeństwa i uczynienia architektury faktycznie wielokrotnego użytku. Kod który jest wystarczająco dobry żeby pokazać nieznajomym, jest lepszym kodem niż ten który nie jest.

Oto pełna lista kontrolna.

Dlaczego open-source projektu osobistego?#

Odpowiedzialność — kod który pokażesz światu jest lepszym kodem. Dyscyplina dokumentacji — piszesz dokumentację gdy nieznajomi mogą ją czytać. I ostateczne ćwiczenie refaktoryzacji: czy byłbyś dumny pokazując ten kod?

notACMS to oparty na Symfony generator statycznych stron bez bazy danych, bez CMS i bez PHP zaangażowanego w serwowanie treści, na licencji Apache 2.0. Jeśli ktoś inny może go użyć, to waliduje architekturę.

Audyt: wynik 9.5/10 gotowości#

Czego brakowało (i jak to naprawiłem)#

GitHub Actions CI/CD — .github/workflows/ci.yml: PHP 8.5, composer install, validate, audit, Twig lint, Rector dry-run, CS Fixer, PHPStan, PHPUnit. Nic nie trafia na produkcję dopóki wszystkie checki nie przejdą.

CONTRIBUTING.md — Setup DDEV, standardy stylu kodu, proces PR, konwencje commitów. Bariera kontrybucji powinna być jedna komenda: ddev start.

SECURITY.md — Obsługiwane wersje, raportowanie luk (prywatne zgłoszenie), polityka aktualizacji bezpieczeństwa. Nawet dla jednoosobowego projektu, posiadanie zdefiniowanego procesu ma znaczenie.

CHANGELOG.md — Format Keep a Changelog 1.1.0, wpis początkowego wydania. Przyszłe wydania będą śledzić co się zmieniło.

Szablony Issue/PR — Raport błędu, propozycja funkcji, wytyczne PR. Dobre szablony redukują obciążenie poznawcze zarówno dla zgłaszającego jak i opiekuna.

CODEOWNERS — Śledzenie własności kodu. Jedna osoba, ale to dobra praktyka i sygnalizuje że projekt jest utrzymywany.

Suite testów — 368 testów z Unit i Integration, opisane w części 1 tej serii.

Rector jako zautomatyzowana refaktoryzacja#

Rector używa withPreparedSets(codeQuality: true, codingStyle: true, deadCode: true, typeDeclarations: true, symfonyCodeQuality: true) plus withPhpSets(php85: true). Dry-run w CI, --fix w ddev code-fix. Co łapie: zbędne checki null, uproszczenia tablic, nowoczesna składnia PHP 8.5, martwy kod, deklaracje typów. Co pomija: ControllerMethodInjectionToConstructorRector — ErrorController potrzebuje wartości runtime których nie da się wstrzyknąć przez konstruktor.

Co pominąłem (i dlaczego)#

Code of Conduct — Jednoosobowy projekt. Brak społeczności do zarządzania. Jeśli się zmieni, to się zmieni.

Informacje o licencjach stron trzecich — Zależności MIT nie wymagają atrybucji w źródle. Może później jeśli projekt urośnie.

100% pokrycia testami — Pozostałe ~20% to wysyłanie emaili, ścieżki kopiowania mediów, __invoke error controllera. Wysoki koszt uruchomienia, niski zwrot. 80% pokrywa wszystkie publiczne API, główne ścieżki kodu i przypadki brzegowe.

Pipeline deployowania#

ddev code-check   # Composer validate + audit, Twig lint, Rector, CS Fixer, PHPStan
ddev test         # 368 testów, 490 asercji
./deploy.sh --prod

Brama jakości: nic nie trafia na produkcję dopóki wszystkie checki nie przejdą. Skrypt deployu działa wewnątrz produkcyjnego kontenera PHP gdzie znana jest poprawna architektura CPU. Po buildzie nginx już serwuje nowe statyczne pliki.

Wynik: notACMS#

Generator statycznych stron oparty na Symfony, na licencji Apache 2.0, z dokumentacją, testami, CI i wzorcem lokalnych nadpisań. Nie framework — szablon projektu który możesz sklonować, customizować przez local/ i deployować. Cały kod, treść i konfiguracja mieści się w jednym repozytorium gita. Backup to git push.

Ta seria zaczęła się od 368 testów, przeszła przez audyt AI, poprawki bezpieczeństwa i wzorzec lokalnych nadpisań. Po wydaniu, kolejne posty opisują pipeline budowania, budowę produkcyjnego motywu i wyszukiwarkę Pagefind. Oryginalna seria o migracji z WordPressa opowiada historię jak ten kod powstał.

Chcesz udostępnić szablon projektu Symfony. Każdy użytkownik musi go dostosować — inne kolory, inna strona główna, inna nawigacja. Forkowanie oznacza że nie może pobierać aktualizacji z upstreama. Pliki konfiguracyjne nie obsłużą zmian w szablonach. Motywy są zbyt sztywne.

Rozwiązanie które zbudowałem dla notACMS to katalog local/ który scala się na projekt bazowy w czasie buildu. Użytkownicy customizują local/, reszta zostaje nienaruszona, a gdy upstream się zmienia — pull i merge jak każda inna operacja gita.

Problem#

Trzy scenariusze których pliki konfiguracyjne nie rozwiążą:

• Użytkownik A chce inne kolory CSS i customowy layout strony głównej
• Użytkownik B chce nadpisać tylko komponent nawigacji
• Użytkownik C chce dodać własne stringi tłumaczeń

Forkowanie to tradycyjna odpowiedź. Ale forkowanie oznacza że każda aktualizacja upstreama to ręczny merge. Dla projektu który dostaje regularne usprawnienia, to obciążenie utrzymaniowe które zabija adopcję.

Rozwiązanie: Warstwa scalania#

local/ leży obok projektu bazowego. W czasie buildu ścieżki rozwiązują się z priorytetem: local/ pierwsze, baza druga. Trzy typy nadpisań:

Pełne nadpisanie — Zamiana całego pliku. local/templates/base.html.twig zastępuje templates/base.html.twig kompletnie.

Nadpisanie bloków — Rozszerzenie i nadpisanie konkretnych bloków Twig:

{% extends 'base.html.twig' %}

{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('styles/custom.css') }}">
{% endblock %}

Nadpisanie tłumaczeń — local/translations/messages.en.yaml scala się z bazowymi tłumaczeniami, dodając lub zastępując klucze:

# local/translations/messages.en.yaml
site.title: "Moja Własna Strona"
nav.home: "Strona główna"

Kolejność CSS: Importmap z dwoma entrypointami#

Najtrudniejsza część. Lokalne style muszą ładować się po stylach bazowych żeby je nadpisać przez kaskadę:

// importmap.php
->add('app', 'assets/app.js')           // baza: importuje app.scss
->add('local', 'assets/local/app.js')   // local: importuje local.scss

local.scss importowany po app.scss, więc kaskada CSS działa poprawnie. Bez !important. Importmap rejestruje oba entrypointy; przeglądarka ładuje je w kolejności.

Rozwiązywanie szablonów#

Kernel::build() sprawdza pliki w local/templates/ i kopiuje je do outputu, nadpisując bazowe szablony. Katalog local/ jest gitignorowany w projekcie użytkownika, ale placeholdery .gitkeep zapewniają że świeże klony mają strukturę:

local/
├── assets/
│   └── styles/
│       └── .gitkeep
├── templates/
│   └── .gitkeep
└── translations/
    └── .gitkeep

Boilplate'y w docs/examples/#

Gotowe szablony startowe do różnych poziomów customizacji:

Co jest śledzone w Gicie#

Pliki .gitkeep w katalogach placeholder local/ żeby struktura istniała w świeżych klonach. Faktyczne pliki nadpisań są gitignorowane — to customizacje użytkownika. docs/examples/ zawiera szablony copy-paste od których użytkownicy zaczynają.

Dlaczego nie framework?#

notACMS nie jest frameworkiem. Użytkownicy nie robią composer install notacms/core. Klonują repo, customizują local/ i deployują. Wzorzec jest na tyle prosty że da się go zrozumieć w 5 minut, i na tyle potężny że obsłuży każdą customizację. Cała powierzchnia customizacji to jeden katalog.

W następnym poście opisuję pełną listę kontrolną wydania open-source — wszystko z poprzednich czterech postów prowadzące do finałowego launchu.

"Statyczne strony są bezpieczne." To najczęstsza rzecz jaką ludzie mówią, gdy powiesz im że zamieniłeś WordPressa na statyczny HTML. I to prawda — o ile "statyczna" oznacza "bez bazy danych i bez kont użytkowników". W momencie gdy statyczna strona ma formularz kontaktowy, wyszukiwarkę albo jakikolwiek JavaScript renderujący treść od użytkownika, powierzchnia ataku nie jest zerowa. Jest po prostu inna.

Oto luki które znalazłem w mojej.

XSS w search.js — i dlaczego oczywista poprawka była błędna#

Pagefind zwraca wyniki wyszukiwania jako JSON. JavaScript renderuje je przez innerHTML. Po code review naturalnym odruchem było escapowanie fragmentu:

// "Naprawione" w 1.1.2
'<p class="post-card-excerpt">' + esc(r.excerpt) + '</p>'

Przeszło review. Wylądowało w kodzie. Potem ktoś coś wyszukał i zauważył że podświetlone trafienie nie jest już pogrubione — wyświetlało się jako literalny tekst:

…wyniki dla <mark>notacms</mark> w…

Pagefind wstrzykuje tagi <mark> do fragmentów w czasie zapytania, żeby podświetlić dopasowane wyrazy. esc() escapował te tagi razem ze wszystkim innym. "Poprawka bezpieczeństwa" po cichu zepsuła podświetlanie wyników.

Revert:

// Aktualny kod
'<p class="post-card-excerpt">' + r.excerpt + '</p>'

To nie jest zostawienie luki. r.excerpt to nie input użytkownika — jest generowany przez pagefind z własnego, pre-indeksowanego statycznego HTML. Jedyny HTML jaki zawiera to tagi <mark> wstrzyknięte przez sam pagefind. Właściwa zasada to nie "zawsze escapuj przed innerHTML" — to wiedz kto kontroluje stringa. Wszystkie inne pola (r.url, r.meta.title, r.meta.category, tagi) są escapowane, bo pochodzą z frontmattera który w teorii może zawierać cokolwiek.

Naiwne escapowanie było gorsze niż brak poprawki: wprowadziło regresję i dało fałszywe poczucie że problem XSS został rozwiązany.

Open redirect przez nagłówek Referer#

Kontrolery podglądu draftów i zaplanowanych postów przełączają widoczność i przekierowują z powrotem:

// Luka (przed 1.1.x)
return $this->redirect($request->headers->get('referer', '/'));

Nagłówek Referer jest kontrolowany przez użytkownika. Atakujący może stworzyć link który przeprowadzi użytkownika przez przełączenie podglądu a potem przekieruje go na dowolną zewnętrzną stronę. Poprawka z 1.1.x walidowała czy cel przekierowania to lokalna ścieżka:

// Naprawione w 1.1.x
$referer = $request->headers->get('referer', '/');
if ($referer && str_starts_with($referer, '/') && !str_starts_with($referer, '//')) {
    return $this->redirect($referer);
}
return $this->redirect('/');

W 1.2.0 to zostało wzmocnione. Sprawdzenie str_starts_with operuje na surowym stringu nagłówka — poprawne, ale kruche przy niestandardowych lub zniekształconych wartościach. Ulepszona wersja używa parse_url() żeby osobno wyodrębnić host i ścieżkę, zwalidować każdy komponent z osobna i przekierować tylko do ścieżki (nigdy do pełnej wartości nagłówka):

// Ulepszone w 1.2.0
$referer = (string) $request->headers->get('referer', '');
$refererParts = parse_url($referer);
$refererHost = is_array($refererParts) ? ($refererParts['host'] ?? null) : null;
$refererPath = is_array($refererParts) ? ($refererParts['path'] ?? '') : '';

if (
    (null === $refererHost || $request->getHost() === $refererHost)
    && str_starts_with($refererPath, '/')
    && !str_starts_with($refererPath, '//')
) {
    return $this->redirect($refererPath);
}
return $this->redirect('/');

Path traversal w MediaController#

Cache wariantów serwuje przeskalowane obrazki. Nazwa pliku wariantu pochodzi z URL:

$variantPath = $this->cacheDir . '/' . $variantFilename;

Bez guarda realpath(), spreparowany URL typu ../../etc/passwd mógłby uciec z katalogu cache. Rozwiązanie to pojedyncze sprawdzenie:

$realCacheDir = realpath($this->cacheDir);
if (false === $realCacheDir || !str_starts_with(dirname($variantPath), $realCacheDir)) {
    throw new NotFoundHttpException('Invalid variant path');
}

CSRF na pre-renderowanych formularzach#

To kwestia architektoniczna, nie błąd. Tokeny CSRF Symfony są powiązane z sesją użytkownika. Ale statyczne strony nie mają sesji — HTML jest generowany raz w czasie buildu. Każdy odwiedzający dostałby ten sam token, wypalony w statycznym pliku, który nie może się zwalidować wobec jego własnej sesji.

Rzeczywiste zabezpieczenia są inne:

1. Turnstile CAPTCHA — zastępuje warstwę ochrony przed botami weryfikacją po stronie serwera
2. X-Requested-With: XMLHttpRequest — blokuje proste submit formularzy z klientów nie-JS
3. Ograniczenie nginx — PHP-FPM dostępne tylko na ^/(api|pl/api)/

Flag Secure cookie — flaga która po cichu psuje dev#

Przekierowanie locale ustawia cookie lang po stronie klienta. ; Secure było w kodzie od pierwszego commita:

document.cookie = COOKIE + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax; Secure';

Potem podczas developmentu na DDEV przez HTTP przekierowanie locale przestało działać. Kliknięcie przełącznika języka nie robiło nic. Cookie po prostu nie było.

; Secure mówi przeglądarce żeby ustawiała cookie tylko na originie HTTPS. Na HTTP po cichu nie robi nic — bez błędu, bez ostrzeżenia, bez komunikatu w konsoli. Mechanizm locale był kompletnie niefunkcjonalny na każdym originie HTTP.

Poprawka to uzależnienie od protokołu:

var secure = window.location.protocol === 'https:' ? '; Secure' : '';
document.cookie = COOKIE + '=' + encodeURIComponent(value) + '; path=/; SameSite=Lax' + secure;

Produkcja jest zawsze HTTPS, więc ; Secure jest tam zawsze dodawane. Dev przez HTTP dostaje działające cookie bez niego. Baner cookie używa bezwarunkowego ; Secure — zgoda na ciasteczka nie musi działać na HTTP dev, więc tam to nie problem.

Lekcja to nie "pamiętaj dodać ; Secure". To że flagi bezpieczeństwa które po cichu nie działają to osobna klasa problemów. Dodajesz je, czujesz się bezpiecznie, i nie wiesz że coś zepsułeś dopóki nie ugrzęźniesz w debugowaniu czegoś zupełnie innego.

Przed czym "statyczna" strona naprawdę chroni#

SQL injection — brak bazy danych. Server-side template injection — szablony kompilowane w czasie buildu. Ataki upload plików — brak uploadów. Ataki brute-force na logowanie — brak strony logowania.

Przed czym nie chroni: XSS po stronie klienta, open redirecty, path traversal w dynamicznych endpointach, CSRF na formularzach, brakujące nagłówki bezpieczeństwa, JavaScript który ufa niezaufanym danym.

Formularz kontaktowy: jedyny dynamiczny endpoint jest najbardziej atakowany#

nginx ogranicza PHP-FPM do jednego wzorca:

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

Reszta serwowana z dysku. Formularz kontaktowy ma weryfikację Turnstile, ciasny CSP który dopuszcza tylko challenges.cloudflare.com jako zewnętrzną domenę, bez 'unsafe-inline' i 'unsafe-eval' w script-src:

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;

'unsafe-inline' w style-src to świadomy kompromis: widget Turnstile wstrzykuje inline styles których nie da się uniknąć bez CSP nonce. Reszta jest zamknięta.

W następnym poście opisuję wzorzec lokalnych nadpisan — jak notACMS pozwala użytkownikom customizować szablony, CSS i tłumaczenia bez forka.

Kod przeszedł PHPStan level 6. PHP CS Fixer nie miał nic do zarzucenia. Rector dry-run czysty. Przejrzałem każdy plik osobiście. Byłem gotowy na open-source.

Potem poprosiłem AI o audyt na podstawie 200-linijkowego pliku instrukcji. Znalazł 79 problemów.

Setup: AGENTS.md jako instrukcja audytu#

Nie "przejrzyj mój kod" — to daje generyczne uwagi o obsłudze błędów i przypadkach brzegowych. Zamiast tego szczegółowa checklista w AGENTS.md:

• Zasady architektury — tylko klasy final, segregacja interfejsów, value objects zamiast tablic asocjacyjnych
• Konwencje nazewnicze — XxxInterface → Xxx, public const w interfejsach
• Wzorce bezpieczeństwa — guardy przed path traversal, walidacja przekierowań, sanitizacja danych
• Zasady stylu kodu — warunki Yody, pusta linia przed return, strict types
• Synchronizacja dokumentacji — tabele serwisów zgodne z src/, tabele zmiennych zgodne z _variables.scss

AI nie zgadywało czego szukać. Wykonywało instrukcje. Różnica jest taka sama jak między przeglądem kodu od kogoś kto zna projekt a przeglądem od kogoś kto go nie zna.

Co AI złapało, a ja przeoczyłem#

Mutowalny stan w cache — ContentTree::setIncludeDrafts() mutował obiekt z cache. Ta sama instancja drzewa była współdzielona między requestami, więc przełączenie draftów w jednym requeście wpływało na następny. Race condition czekający na okazję. Rozwiązanie: uczynić ContentTree niemutowalnym i przenieść filtrowanie draftów do warstwy serwisu.

Naruszenia SOLID — SiteConfigServiceInterface miał 16 metod. Zasada projektu to max 5. ContentTree miał 20+ metod robiących strukturę danych, silnik zapytań i scoring rekomendacji — trzy zadania w jednej klasie. Rozwiązanie: wyciągnąć RelatedPostsService (73-linijkowy algorytm scoringu → osobny serwis z własnym interfejsem).

Zduplikowana logika — readingTime() i excerpt() obie robiły strip_tags + str_word_count na tej samej zawartości HTML. Wyciągnięte do wspólnej metody getPlainText().

Luki w dostępności — Zagnieżdżone elementy <label> w formularzu kontaktowym (niepoprawny HTML), brakujące role="alert" na spanach błędów, aria-current="true" zamiast "page". Każde poprawka na jedną linię, ale niewidoczne bez checklisty.

Gnicie dokumentacji — docs/STYLEGUIDE.md podający Bootstrap blue (#0d6efd) zamiast faktycznego zielonego (#2d8a4e). docs/ARCHITECTURE.md odwołujący się do fantomowych plików: tagline.js, contact_widget.html.twig, _header.scss — żaden nie istniał.

Co AI źle oceniło (false positives)#

CSRF na formularzu kontaktowym — oznaczone jako luka, ale celowe. Statyczne, pre-renderowane strony nie mogą używać tokenów CSRF powiązanych z sesją — token jest wypalony w HTML w czasie buildu, powiązany z sesją serwera buildowego. Każdy odwiedzający dostaje ten sam token. Turnstile + nagłówek X-Requested-With zapewniają rzeczywistą ochronę.

Dane użytkownika w komunikatach błędów 404 — oznaczone jako ryzyko enumeracji, ale te komunikaty pojawiają się tylko podczas statycznego buildu, nie dla odwiedzających. Produkcyjne strony błędów Symfony nie ujawniają komunikatów wyjątków.

"Niejodyczne" porównania — oznaczone wzorce zmienna-vs-metoda jak $page->directoryKey() === $directoryKey, ale prawdziwa reguła Yody dotyczy literałów (null, false, stringi) po lewej. Porównania zmienna-vs-zmienna nie wymagają odwracania.

Co zmieniłem vs co zaakceptowałem#

Około 60 problemów naprawionych. Około 19 zaakceptowanych:

• Zduplikowane serwisy podglądu — DraftPreviewService i ScheduledPreviewService są prawie identyczne, ale każdy ma 3 linie. Sparametryzowanie wymagałoby ServiceLocatora, wstrzykiwania enuma i customowej serializacji na data collectorze. Więcej złożoności niż oryginał. Zaakceptowane.
• Szeroki SiteConfigServiceInterface — 16 metod, ale to obiekt konfiguracyjny, nie serwis biznesowy. Podział dotyka 20 plików dla porządku anotacji tylko. Zaakceptowane.

Naprawki, które się liczyły:

// Przed: mutowalne drzewo w cache
$tree->setIncludeDrafts(true);  // mutuje współdzieloną instancję

// Po: niemutowalne drzewo, filtrowanie w warstwie serwisu
$posts = $this->contentService->getPosts($locale, includeDrafts: true);

// Przed: 73-linijkowy algorytm w ContentTree
public function getRelatedPosts(ContentItem $post, int $limit = 3): array
{
    // ... 73 linie scoringu tagów/kategorii/serii
}

// Po: osobny serwis
final class RelatedPostsService implements RelatedPostsServiceInterface
{
    public function findRelated(ContentItem $post, ContentTree $tree, int $limit = 3): array
    {
        // ... ta sama logika, ale izolowana
    }
}

Wniosek#

"Przejrzyj mój kod" daje generyczne uwagi. "Audytuj według tych 200 linii standardów projektu" daje konkretne, akcjonowalne wyniki. AGENTS.md nie służy tylko do budowania — służy też do przeglądów. AI złapało rzeczy, na które patrzyłem dziesiątki razy, bo sprawdzało według reguł, a nie polegało na znajomości.

W następnym poście opisuję luki bezpieczeństwa wśród tych 79 problemów: XSS w wyszukiwarce, open redirecty i path traversal na "statycznej" stronie.

Treści to pliki Markdown. Szablony to Twig. Style to SCSS. Nie ma bazy danych, nie ma API, nie ma kont użytkowników. Co tu właściwie testować?

Sporo. Logika parsująca frontmatter, budująca drzewo treści, obliczająca mapy tłumaczeń, generująca responsywne srcsety i rozwiązująca zlokalizowane trasy to czyste PHP — i jest podatne na błędy jak każdy inny kod. Większość statycznych generatorów stron ma zero testów. notACMS ma 368.

Dlaczego testować statyczną stronę?#

Pliki z treścią nie potrzebują testów. Potrzebuje ich pipeline, który je przetwarza: ContentTreeBuilder skanujący katalogi, MarkdownParser wyciągający frontmatter, ContentService cache'ujący wyniki, TranslationMapBuilder obliczający mapy locale→URL, LocalizedRouteLoader generujący trasy z _routes.yaml. Wszystko to czysta logika bez zależności od bazy danych — idealna do testów jednostkowych.

Piramida testów dla aplikacji opartej na treściach wygląda inaczej niż dla typowej aplikacji webowej:

• Testy jednostkowe — ContentItem, ContentTree, Value Objects. Bez mocków, bez kernela. Tablice frontmattera wchodzą, oczekiwane właściwości wychodzą.
• Testy jednostkowe ze stubami — SiteConfigService, TagTranslationService, SrcsetExtension. Stuby interfejsów dla zależności, katalogi tymczasowe dla operacji na plikach.
• Testy integracyjne — kontrolery, komendy, serwisy z uruchomionym kernelem Symfony. Testy smoke HTTP dla kluczowych tras.

Liczby#

368 testów, 490 asercji, ~80% pokrycia linii, ~82% pokrycia metod. Trzy fazy:

Faza 1: Czyste testy jednostkowe (191 testów) — ContentItem z isDraft, isScheduled, isPinned, readingTime, excerpt i dziesiątkami przypadków parsowania frontmattera. ContentTree filtrujący po kategorii, tagu, miesiącu archiwum, paginacji. Value Objects: AdjacentPosts, ArchiveMonth, CategoryCount, ParsedMarkdown, ParsedVariant, RenderResult, SidebarData, TagCount. Bez mocków, bez kernela, bez systemu plików.

Faza 2: Testy jednostkowe ze stubami interfejsów (49 testów) — SiteConfigService czytający YAML z katalogów tymczasowych, TagTranslationService tłumaczący tagi między locale, SrcsetExtension generujący atrybuty srcset. createStub() dla interfejsów które nie potrzebują expects(), TmpDirTrait do sprzątania plików.

Faza 3: Testy integracyjne (127 testów) — BlogController zwracający 200 dla poprawnych stron i 404 dla nieistniejących, ContactController obsługujący formularz, BuildStaticSiteCommand kończący się bez błędów, LocalizedRouteLoader generujący poprawne trasy. Kernel Symfony startuje, drzewo treści się buduje, klient HTTP wykonuje requesty.

Co warto testować#

ContentItem::isScheduled() poprawnie wykrywający przyszłe daty — włącznie z przypadkiem granicznym gdzie data to dokładnie teraz (przedział prawostronnie otwarty: post jest już opublikowany na granicy). ContentTree::getPaginatedPosts() poprawnie dzielący na strony. LocalizedRouteLoader generujący trasy dla każdego locale. BuildStaticSiteCommand kończący się bez błędów.

Czego NIE warto testować: ścieżki wysyłania emaili w ContactController (wymaga mockowania mailera, testowania infrastruktury której nie posiadam), operacji kopiowania plików w BuildStaticSiteCommand (wymaga prawdziwego systemu plików z obrazkami), ErrorController::__invoke (trudne do wywołania przez klienta HTTP). Wysoki koszt uruchomienia, niski zwrot.

Konwencje testowe, które mają znaczenie#

ContentItemFactory dla wszystkich fixture'ów — Nigdy nie konstruuj ContentItem bezpośrednio w testach. Fabryka dostarcza sensowne wartości domyślne i nazwane konstruktory:

$post = ContentItemFactory::publishedPost([
    'title' => 'Test Post',
    'tags'  => ['testing', 'php'],
], 'test-post', '/blog/test-post/');

Asercje XPath, nie selektory CSS — symfony/css-selector nie jest zainstalowany, więc $crawler->filter('.class') rzuca LogicException. Używaj filterXpath():

$meta = $crawler->filterXpath('//meta[@name="robots"]/@content');
self::assertGreaterThan(0, $meta->count());
self::assertStringContainsString('noindex', $meta->text());

createStub() vs createMock() — PHPUnit 13 wyświetla ostrzeżenia dla mocków bez expects(). Używaj createStub() w setUp() dla interfejsów gdzie potrzebujesz tylko wartości zwrotnej. Twórz createMock() lokalnie tylko w testach które weryfikują liczbę wywołań:

// setUp() — bez expects, użyj createStub()
$this->config = $this->createStub(SiteConfigServiceInterface::class);
$this->config->method('getPostsPerPage')->willReturn(10);

// Pojedynczy test — ma expects, użyj createMock()
$mock = $this->createMock(MarkdownParserInterface::class);
$mock->expects(self::once())->method('parse')->willReturn($parsed);

declare(strict_types=1) w każdym pliku testowym — Tak jak w kodzie produkcyjnym. Warunki Yody w asercjach. Pusta linia przed return.

Integracja z CI#

ddev test uruchamia pełny zestaw z outputem testdox. GitHub Actions uruchamia suite Unit przy każdym pushu:

- name: PHPUnit
  run: vendor/bin/phpunit --testsuite Unit

Testy integracyjne potrzebują pełnego kernela i plików z treścią — działają lokalnie przez DDEV, ale Unit-only w CI to właściwy kompromis. Suite Unit łapie regresje w rdzeniu logiki; testy integracyjne łapią problemy z konfiguracją które pojawiają się tylko z pełnym stosem.

Efekt#

Kiedy celnie zepsułem ContentItem::isDraft(), suite testowy złamał to natychmiast — 12 testów padło z jasnymi komunikatami o tym, która właściwość była niepoprawna. Przed suite'em testowym, taka regresja wyszłaby dopiero gdy ktoś zauważyłby draft na żywej stronie.

368 zielonych testów to pewność przy refaktoryzacji. Wyciąganie RelatedPostsService z ContentTree, uczynienie drzewa niemutowalnym, przenoszenie stałych do interfejsów — wszystko to działo się z siatką bezpieczeństwa testów które wyłapałyby cokolwiek co by się zepsuło.

W następnym poście opisuję co stało się dalej: audyt AI znalazł 79 problemów w kodzie który przeszedł już PHPStan, CS Fixer i ręczny przegląd. Testy łapią tylko to, o czym pomyślisz. Audyt łapie to, o czym zapomniałeś pomyśleć.

Kilka miesięcy temu pisałem o uruchomieniu audytu AI na notACMS i znalezieniu 79 bugów. 1.2.0 to kontynuacja: kolejne pełne przejście, tym razem z projektem w lepszym stanie i bogatszym AGENTS.md prowadzącym przegląd. Znalazło się sporo oczywistych rzeczy i kilka nieoczywistych. Oto te warte opisania.

Bug w nginx który po cichu psował formularze#

Najbardziej frustrujące znalezisko: formularz kontaktowy który działał perfekcyjnie w każdym środowisku poza produkcją w Dockerze.

Konfiguracja nginx używała lokalizacji z regexem do routowania API kontaktowego:

location ~ ^/[a-z]{2}/api/contact$ {

Tylko że nie działała. W składni nginx {2} w pewnych kontekstach jest traktowane dosłownie — kwantyfikator był dopasowywany jako ciąg znaków, nie jako "dokładnie dwa znaki". Regex nigdy nie pasował, więc POST /pl/api/contact nigdy nie trafiał do PHP. Każda niedomyślna lokalizacja dostawała ciche 404 przy wysłaniu formularza.

Działało w DDEV (który ma własną konfigurację nginx) i lokalnie (gdzie PHP obsługuje routing inaczej). Docker produkcyjny, korzystający z commitowanego nginx.conf.template, był zepsuty od samego początku. Poprawka: jeden znak, zaescapowanie nawiasów klamrowych.

locale-redirect: pomocność szkodliwa#

Skrypt locale-redirect.js czyta preferencje językowe przeglądarki i przekierowuje nowych użytkowników na ich lokalizację. Sensowny pomysł, ale logika miała dziurę.

Kiedy ktoś trafia na /pl/ pierwszy raz bez ciasteczka lang — powiedzmy, klikając w link — skrypt czytał navigator.language, znajdował en-US, ustawiał ciasteczko na en i przekierowywał go z dala od strony, na którą celowo wszedł.

Poprawka jest oczywista z perspektywy czasu: jeśli aktualny URL jest już na niedomyślnej lokalizacji, sam URL jest preferencją. Ustaw ciasteczko i stop. Bez przekierowania. Obejmuje to też środowiska HTTP — flaga Secure po cichu traciła ciasteczko w non-HTTPS (domyślna konfiguracja DDEV), uniemożliwiając działanie całego mechanizmu.

Dorzuciłem też zabezpieczenie przed scenariuszem którego wcześniej nie przewidziałem: przestarzałe ciasteczko z lokalizacją która zniknęła z _site.yaml. Bez niego usunięcie języka ze strony wpędzałoby każdego odwiedzającego ze starym ciasteczkiem w nieskończoną pętlę przekierowań na 404.

Excerpty wyszukiwarki i podwójne escapowanie#

Przegląd bezpieczeństwa z 1.1.2 znalazł XSS w wyszukiwarce: excerpty z pagefind były wstrzykiwane do innerHTML bez escapowania. Naprawione przez owinięcie w esc().

Tyle że excerpty pagefind zawierają tagi <mark> — tak pagefind zaznacza dopasowania. Poprawka zepsuła wyróżnianie: <mark>term</mark> zamieniło się w dosłowny tekst <mark>term</mark>. Właściwa odpowiedź: treść pagefind to autorski statyczny HTML, nie dane wejściowe użytkownika. Tagi <mark> są wstrzykiwane przez silnik wyszukiwania na etapie budowania, nie przez odwiedzających. Usuń esc() z excerpta, zostaw wszędzie indziej. Niewidoczne dopóki nie zauważysz że wyróżnienia nie wyróżniają.

Bezpieczeństwo i utwardzenie#

ImageMagick działa teraz przez Symfony\Process z tablicami argumentów zamiast ciągów shell — exec() zniknął. Turnstile weryfikuje hostname w odpowiedzi siteverify względem skonfigurowanego base_url, więc tokeny wygenerowane na domenie testowej nie mogą być odtworzone w produkcji. Output JSON-LD jest hex-escapowany — </script> w tytule posta nie może już wyłamać się ze skryptu. Nagłówki bezpieczeństwa nginx (X-Frame-Options, CSP itd.) nie docierały do odpowiedzi /assets/ i /media/ — add_header na poziomie lokalizacji wyciszał dziedziczone nagłówki serwera.

/llms.txt#

Mały dodatek: trasa /llms.txt dołączona do statycznego builda, wylistowująca najnowsze wpisy w formacie czytelnym maszynowo — per lokalizacja, konfigurowalne przez llms_limit w _site.yaml, nadpisywalne per-motyw przez przestrzeń nazw Twig @base. Statyczne strony nie są tradycyjnie łatwe do nawigowania dla modeli językowych — to niskokosztowy sposób na dostarczenie kontekstu komukolwiek (lub czemukolwiek) kto to czyta.

Breaking changes#

Kilka zmian wymagających jednolinijkowej migracji w local/src/:

• ContentItem::directoryKey() zwraca teraz pełną ścieżkę treści (pages/about nie about), naprawiając ciche kolizje URL między katalogami o tej samej nazwie w różnych sekcjach
• getTree() przeniesione do ContentTreeProviderInterface — z ContentServiceInterface
• structured_data().blogPosting() przyjmuje nazwaną mapę (było 13 pozycyjnych argumentów)
• Klucz kontekstu lang_switch_url usunięty — użyj lang_switch
• docs/customization/old-template/ usunięty z repo — pobierz z taga v1.1.x jeśli nadal potrzebujesz

Pełny przewodnik migracji: UPGRADE-1.2.md.

Linki#

Pełny changelog: CHANGELOG.md.

Repozytorium: GitHub / holas1337/notACMS — Apache 2.0.

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/2026-05-16-seo-engineering-static-site/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/2026-05-16-seo-engineering-static-site/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-dir/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.