Upgrade z CakePHP 4 do CakePHP 5

CakePHP 5 wprowadza nowoczesne API, lepsze wsparcie dla PHP 8.1+, wyższą wydajność oraz usuwa wiele przestarzałych elementów z serii 4.x. W tym tutorialu przejdziemy krok po kroku przez cały proces migracji. Zanim rozpoczniesz aktualizację wykonaj pełny backup projektu oraz bazy danych.

1. Wymagania systemowe

CakePHP 5 wymaga PHP 8.1 lub nowszego. Sprawdź wersję poleceniem:

php -v

Instalacja wymaganych rozszerzeń np.:

sudo apt install php8.2 php8.2-intl php8.2-mbstring php8.2-xml

2. Backup projektu

Przed upgradem wykonaj commit oraz tag w Git.

git commit -am "Before CakePHP 5 upgrade"
git tag before-cakephp5-upgrade

Dodatkowo wykonaj:

• backup bazy danych
• backup composer.json
• backup pliku .env

3. Aktualizacja CakePHP 4 do najnowszego 4.x

Najpierw zaktualizuj projekt do ostatniej wersji CakePHP 4.

composer update

Włącz pełne raportowanie błędów:

'Error' => [
    'errorLevel' => E_ALL,
]

Włącz debug mode:

'debug' => true,

4. Instalacja narzędzia upgrade

CakePHP udostępnia oficjalne narzędzie upgrade pomagające w migracji.

composer require --dev cakephp/upgrade

5. Automatyczna analiza kodu

Uruchom rectora dla katalogu src:

bin/cake upgrade rector --rules cakephp50 src/

oraz dla templates:

bin/cake upgrade rector --rules cakephp50 templates/

6. Aktualizacja composer.json

Stary composer.json

"require": {
    "php": ">=7.4",
    "cakephp/cakephp": "^4.4"
}

Nowy composer.json

"require": {
    "php": ">=8.1",
    "cakephp/cakephp": "^5.0"
}

7. Aktualizacja zależności

Po zmianie composer.json uruchom:

composer update

Jeśli wystąpi konflikt zdiagnozuj, które pakiety powodują problem:

composer why-not cakephp/cakephp 5.0

8. Aktualizacja pluginów

Najczęściej aktualizacji wymagają:

• Authentication
• Authorization
• DebugKit
• Migrations

composer update cakephp/authentication
composer update cakephp/authorization

9. Response immutable

W CakePHP 5 obiekt response jest immutable tzn. niemodyfikowalny. Oznacza, że nie zmieniasz bezpośrednio istniejącej instancji obiektu. Zamiast tego modyfikacje tworzą i zwracają nową instancję obiektu odpowiedzi. W starszych wersjach modyfikowało się obiekt w miejscu. W CakePHP 5 musisz przypisać zwrócony obiekt z powrotem do zmiennej.

Stary kod

$this->response->type('json');

Nowy kod

$this->response = $this->response->withType('application/json');

10. RequestHandlerComponent

Stary kod

$this->RequestHandler->renderAs($this, 'json');

Nowy kod

$this->viewBuilder()->setOption('serialize', true);

11. Typowanie metod

CakePHP 5 mocniej wykorzystuje type hints.

public function initialize(): void
{
}

public function index(): Response
{
}

12. Middleware

Sprawdź konfigurację middleware w Application.php.

$middlewareQueue
    ->add(new ErrorHandlerMiddleware())

13. Czyszczenie cache

bin/cake cache clear_all

rm -rf tmp/cache/*

14. Testy aplikacji

Po zakończeniu migracji uruchom testy:

vendor/bin/phpunit

Sprawdź również routes:

bin/cake routes

Podsumowanie

Migracja z CakePHP 4 do CakePHP 5 jest stosunkowo prosta, jeżeli projekt był regularnie aktualizowany i nie zawiera dużej ilości deprecated API.

Najważniejsze kroki:

• aktualizacja do najnowszego 4.x
• usunięcie deprecated warnings
• aktualizacja PHP
• upgrade composer dependencies
• aktualizacja cakephp
• aktualizacja pluginów
• testy aplikacji