Magento 2: bloki CMS przez Data Patch bez boilerplate

Klikanie bloków i stron CMS w panelu administracyjnym Magento 2 to najprostsza droga do rozjazdu danych między środowiskiem lokalnym, stagingiem a produkcją. Zamiast ręcznego wklejania HTML-a po każdym wdrożeniu lub generowania dziesiątek linii powtarzalnego kodu z repozytoriami i fabrykami, zawartość CMS powinna lądować bezpośrednio w systemie kontroli wersji. Do tego celu w projektach e-commerce wykorzystujemy moduł SimpleData, który redukuje tworzenie oraz aktualizację treści do prostego, idempotentnego zapisu w natywnym Data Patchu.

Dlaczego ręczne wyklikiwanie CMS-a w Magento 2 to ślepy zaułek?

Wdrożenia e-commerce w architekturze wielośrodowiskowej (Local → Stage → Production) wymagają pełnej powtarzalności. Gdy deweloper tworzy nowy komponent layoutu wymagający dedykowanego bloku CMS z widgetem lub specyficzną strukturą HTML, scenariusz z ręcznym kopiowaniem zawartości przez panel admina rodzi szereg problemów:

• Błędy ludzkie: Przypadkowe pominięcie widoku sklepu (Store View), literówka w identyfikatorze (Identifier) czy brakujące reguły cache powodują błędy renderingu na produkcji.
• Brak historii zmian: Zmiany wprowadzane bezpośrednio w bazie danych nie podlegają procesowi Code Review i znikają z historii Gita. Nie wiesz, kto, kiedy i dlaczego zmodyfikował kluczowy baner.
• Wydłużony deployment: Wdrożenie produkcyjne nie powinno zawierać checklisty typu: zaloguj się do admina, utwórz blok X, wklej kod Y, przypisz do widoku Z. Wszystko ma wykonać się automatycznie podczas polecenia bin/magento setup:upgrade.

Naturalnym krokiem jest więc przeniesienie definicji bloków do kodu PHP za pomocą mechanizmu DataPatchInterface.

Jak wygląda standardowy Data Patch w Magento i co z nim nie tak?

Natywne podejście Adobe Commerce do tworzenia danych początkowych (data seeding) jest poprawne architektonicznie, ale potwornie rozwlekłe. Aby stworzyć pojedynczy blok statyczny zgodnie ze sztuką Magento, musisz wstrzyknąć do konstruktora klasy:

• Magento\Cms\Api\BlockRepositoryInterface
• Magento\Cms\Api\Data\BlockInterfaceFactory
• Magento\Framework\Api\SearchCriteriaBuilder (do weryfikacji, czy blok już istnieje)

W efekcie otrzymujesz klasę mającą 80-120 linii kodu tylko po to, by wstawić do bazy prosty kontener na stopkę lub komunikat o darmowej dostawie. Co gorsza, jeśli chcesz zaktualizować treść istniejącego bloku, standardowy patch albo wyrzuci wyjątek o zduplikowanym identyfikatorze, albo zmusi Cię do ręcznego pisania logiki typu upsert (wyszukaj po identifierze, załaduj model, nadpisz pola, zapisz).

Standardowy kod Magento wymusza pisanie kilkudziesięciu linii powtarzalnego kodu dla operacji, która w gruncie rzeczy sprowadza się do prostej tablicy klucz-wartość.

Czym jest SimpleData i dlaczego rozwijamy własny fork?

Rozwiązaniem tego problemu jest moduł SimpleData, pierwotnie stworzony przez znanego edukatora i architekta Magento, Marka Shusta (oryginalne repozytorium zdobyło ponad 94 gwiazdki na GitHubie). Koncepcja narzędzia polega na dostarczeniu warstwy abstrakcji dla operacji CMS — zamiast konfigurować repozytoria i fabryki, deweloper dziedziczy po klasie bazowej i wykonuje jedno wywołanie metody z tablicą parametrów.

Oryginalny moduł Marka Shusta przestał być jednak aktywnie rozwijany w 2023 roku, co przy dynamicznych zmianach w ekosystemie (PHP 8.2, 8.3, 8.4 oraz wydania Magento 2.4.7+) doprowadziło do problemów z kompatybilnością typowania i standardów kodu.

Jako zespół SISL przejęliśmy utrzymanie tego narzędzia. Nasz fork jest w pełni kompatybilny z Magento 2.4.9, PHP 8.4 i rygorystycznymi standardami analizy statycznej PHPStan. Kod źródłowy jest w pełni otwarty i dostępny publicznie na GitHubie: https://github.com/SISL-source/magento2-simpledata.

Jak zainstalować moduł w swoim projekcie?

Instalacja w projekcie opartym na Composerze sprowadza się do dodania repozytorium VCS oraz pobrania paczki. W katalogu głównym projektu Magento wykonaj następujące polecenia:

composer config repositories.sisl-simpledata vcs https://github.com/SISL-source/magento2-simpledata
composer require markshust/magento2-module-simpledata:dev-main
bin/magento module:enable MarkShust_SimpleData && bin/magento setup:upgrade

Po wykonaniu tych kroków moduł dostarcza klasy pomocnicze gotowe do wstrzyknięcia lub dziedziczenia w dowolnym patchu instalacyjnym Twojego modułu projektowego.

Jak stworzyć czysty Data Patch dla bloków i stron CMS?

Główną zaletą SimpleData jest idempotentność operacji save(). Moduł sam sprawdza, czy blok lub strona o danym identifier już istnieje w bazie danych. Jeśli tak — aktualizuje rekord. Jeśli nie — tworzy nowy. Dzięki temu ten sam patch może być bezpiecznie uruchamiany wielokrotnie lub reindeksowany w testach.

Poniżej znajduje się kompletny przykład klasy patcha, która bez żadnego zbędnego boilerplate'u tworzy zarówno blok CMS, jak i stronę informacyjną:

<?php
declare(strict_types=1);

namespace Vendor\CustomModule\Setup\Patch\Data;

use MarkShust\SimpleData\Setup\Patch\Data\SimpleDataPatch;

class AddFooterPromoAndPolicyContent extends SimpleDataPatch
{
    public function apply(): void
    {
        // Idempotentny zapis bloku CMS
        $this->block->save([
            'identifier' => 'footer_shipping_promo',
            'title'      => 'Stopka: Komunikat o wysyłce',
            'content'    => '<div class="shipping-alert"><p>Darmowa dostawa od 250 zł na terenie Polski.</p></div>',
            'is_active'  => 1,
            'stores'     => [0], // 0 = Wszystkie widoki sklepu
        ]);

        // Idempotentny zapis strony CMS
        $this->page->save([
            'identifier'      => 'czas-i-koszty-dostawy',
            'title'           => 'Czas i koszty dostawy',
            'content_heading' => 'Informacje o realizacji zamówień',
            'content'         => '<p>Wszystkie zamówienia wysyłamy kurierem w ciągu 24 godzin roboczych.</p>',
            'page_layout'     => '1column',
            'is_active'       => 1,
            'stores'          => [0],
        ]);
    }
}

Zwróć uwagę na przejrzystość: brak konstruktora przeładowanego zależnościami, brak manualnych pętli sprawdzających kolekcje i zero podatności na błędy kluczy obcych. Cała logika pomocnicza jest ukryta w klasie SimpleDataPatch.

Kiedy warto zrezygnować z panelu na rzecz kodu?

W dojrzałym procesie deweloperskim Magento 2 panel administracyjny powinien służyć managerom e-commerce do bieżących korekt marketingowych i publikowania wpisów blogowych. Wszelkie elementy bazowe systemu — szkielety stron polityk, stałe elementy layoutu wstrzykiwane przez pliki XML, moduły stopki czy struktury pod landing page — powinny być zdefiniowane w kodzie.

Stosując Data Patche oparte o SimpleData zyskujesz:

1. Powtarzalność środowisk: Nowy deweloper stawia środowisko lokalne za pomocą pojedynczego polecenia i ma od razu kompletny, ostylowany sklep z działającymi blokami.
2. Bezpieczeństwo pipeline'u CI/CD: Deploy na serwer produkcyjny nie wymaga asysty człowieka klikającego po panelu.
3. Czysty audyt w Git: Każda zmiana w bazowym HTML-u komponentów przechodzi przez standardowy Pull Request.

Jeśli optymalizujesz procesy CI/CD w swoim sklepie lub chcesz uporządkować dług technologiczny w architekturze Magento, napisz do nas — pomożemy Ci wdrożyć standardy, które realnie przyspieszają pracę zespołu i eliminują błędy wdrożeniowe.