Laminas – migracja projektu opartego o Zend Framework 3

laminas migracja projektu zend framework 3

Laminas to kontynuacja Zend Framework 3. Projekt został wzięty pod skrzydła przez Linux Foundation, która na swoim koncie ma już mnóstwo rozwiązań Open Source. Nazwa Laminas wzięła się od cienkich warstw i jest ona znacząca dla kierunku rozwoju frameworka. Ta warstwowość zapewnia odpowiedni podział i możliwość korzystania z wielu komponentów niezależnie.

Wszystkie projekty Zenda nadal będą rozwijane tyle że pod innym brandem, odpowiednio:

  • Zend Framework -> Laminas Components and MVC
  • Apigility -> Laminas API Tools
  • Expressive -> Mezzio.

Natomiast wszystkie repozytoria zendowych komponentów zostały oznaczone jako archiwalne, nie są już rozwijane i wspierane. Twórcy zapewnili jednak dość prostą migrację do Laminasa opierającą się głównie o zmianę przestrzeni nazw.

Opis środowiska i projektu, który migrowałem z ZF3

Co do środowiska, ja korzystam z linuxa, więc jeśli macie inny system to mam nadzieję, że potraficie przełożyć to na swoje potrzeby. Do przeprowadzenia migracji potrzebny będzie Composer – ale skoro posiadacie już projekt na Zend Framework 3 to narzędzie powinno być Wam znane. Minimalna wersja to 1.7, a ja użyłem najnowszej na ten moment, czyli 1.9.1.

Zawsze mam problem z określeniem wielkości projektu. Co to znaczy, że jest mały, średni czy duży. W związku z tym przedstawię go trochę w liczbach żeby nakreślić jego skalę. Oczywiście te numerki jednoznacznie nie określają wielkości, bo można commitować każdą linijkę osobno albo tak duplikować kod, że staje się obszerniejszy. Niemniej jednak daje to pewien zarys.

Niespełna 3 lata żywotności, a od ponad 2 lat produkcyjnie wykorzystywany i rozwijany. Ponad 10 000 commitów do mastera. Około 250k linii kodu projektu (oczywiście bez zewnętrznych bibliotek) z czego około 60% to PHP (reszta to HTML/CSS /JS).

Migracja do Laminasa

W dokumentacji wymienione zostały trzy sposoby instalacji narzędzia do migracji Lamianasa. Ja wykorzystałem pierwszy z nich, czyli globalna instalacja dla Composera, jako że będę migrował też inne systemy. Zainstalowane narzędzie znajduje się w lokalizacji Composera w katalogu /vendor/bin. W moim przypadku w katalogu domowym /home/koddlo/.composer/vendor/bin.

composer global require laminas/laminas-migration

Teraz należy rozszerzyć zmienną systemową $PATH o katalog, w którym znajduje się plik wykonywalny do narzędzia migracji Laminasa. Istnieje opcja dodania go na stałe, ale nie widzę potrzeb – migracje to raczej jednorazowe akcje. Można więc użyć komendy export – pamiętajcie żeby dostosować swoją lokalizację pliku jeśli jest inna.

export PATH=$HOME/.composer/vendor/bin:$PATH

I to tyle jeśli chodzi o narzędzie. Następnie w terminalu przechodzimy do głównego katalogu projektu i zaczynamy zabawę. Poniższą komendę można wywołać też z flagami -e i -f, które pozwolą wykluczyć konkretne pliki i katalogi.

laminas-migration migrate

I teraz po kolei – co to polecenie robi:

  • usuwa plik composer.lock
  • usuwa katalog /vendor
  • zmienia nazwy zależności w composer.json
  • w całym projekcie zmienia Zend na Laminas (głównie namespace).

Zostało już tylko standardowe dociągnięcie wszystkich zależności uruchamiając:

composer install

W teorii to wszystko. W praktyce oczywiście trzeba posprawdzać – przeklikać, uruchomić testy i tak dalej. Warto też wyszukać w całym projekcie frazy Zend i zobaczyć, czy gdzieś powinna zostać zamieniona, ale tak się nie stało.

Ja podczas migracji wielu projektów natrafiłem na dwa problemy. Gdzieś w Module.php zapięte było polskie tłumaczenie, więc musiałem zmienić ręcznie z Zend_Validate.php na Laminas_Validate.php, o czym bardzo szybko zostałem poinformowany w postaci rzuconego wyjątku.

$translator->addTranslationFile(
    PhpArray::class, 
    __APPLICATION_DIR__ . '../vendor/laminas/laminas-i18n-resources/languages/pl/Zend_Validate.php'
);

Drugi to błąd przekroczenia dozwolonej pamięci dla większych projektów. Wówczas wystarczy wywołać komendę z opcją memory_limit=-1 tak jak poniżej.

Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 79691784 bytes) in /root/.composer/vendor/laminas/laminas-zendframework-bridge/src/Replacements.php on line 38
php -d memory_limit=-1 /root/.composer/vendor/bin/laminas-migration migrate

Poza tym wygląda, że wszystko działa bez zmian. Z tego co śledziłem tworzenie tego narzędzia na początku pojawiło się kilka błędów, ale błyskawicznie zostały poprawione. W momencie, gdy ja go użyłem wszystko zadziałało poprawnie. Jeśli macie już migracje do Laminasa za sobą to podzielcie się w komentarzach swoimi doświadczeniami.

Krystian Żądło
Programista PHP i właściciel marki Koddlo. Pasjonat czystego kodu i dobrych praktyk programowania obiektowego. Prywatnie fan angielskiej piłki nożnej, dobrego humoru oraz podcastów.