Tworzenie i uruchamianie projektu CakePHP z ServBay

ServBay to zaawansowane, lokalne środowisko programistyczne dla macOS, które integruje wsparcie dla wielu języków (PHP, Node.js, Python, Go, Java) oraz usług bazodanowych (MySQL, PostgreSQL, MongoDB, Redis), a także serwery WWW (Caddy lub Nginx). Umożliwia deweloperom szybkie tworzenie, zarządzanie i rozwijanie aplikacji w komfortowych warunkach, eliminując konieczność manualnej konfiguracji komponentów.

Ten artykuł pokaże, jak od zera stworzyć, skonfigurować i uruchomić projekt CakePHP w środowisku ServBay. CakePHP to popularny framework PHP dla aplikacji webowych oparty na wzorcu MVC (Model-View-Controller), ceniony za szybkie tempo developmentu, zaawansowany ORM oraz wbudowane mechanizmy bezpieczeństwa. Dzięki wygodzie ServBay, możesz błyskawicznie rozpocząć pracę nad własną aplikacją w CakePHP.

Czym jest CakePHP?

CakePHP to otwartoźródłowy framework PHP do tworzenia aplikacji webowych. Dostarcza gotową strukturę, która znacznie przyspiesza i porządkuje proces developmentu, nie ograniczając przy tym elastyczności. Stawia na zasadę „konwencja ponad konfigurację”, co pozwala ograniczyć powtarzalną pracę programistyczną.

Główne cechy i zalety CakePHP

• Oparty o wzorzec MVC: Przejrzysta organizacja kodu, łatwa rozbudowa i utrzymanie.
• Szybkie tworzenie aplikacji: Narzędzia CLI (Bake) pozwalają błyskawicznie wygenerować struktury kodu.
• Potężny ORM (mapowanie obiektowo-relacyjne): Prostsza obsługa baz danych z wsparciem wielu silników.
• Wbudowane bezpieczeństwo: Zabezpieczenia CSRF, ochrona przed SQL Injection, walidacja danych i więcej.
• Elastyczny silnik szablonów: Obsługuje różne technologie prezentacji.
• Aktywna społeczność i bogaty ekosystem pluginów: Łatwo znaleźć rozwiązania i rozszerzenia.
• Wyjątkowo rozbudowana dokumentacja: Kompleksowe przewodniki i odwołania do API.

CakePHP sprawdza się zarówno w małych API, jak i rozbudowanych aplikacjach korporacyjnych.

Tworzenie środowiska CakePHP z ServBay

ServBay oferuje wygodnie zintegrowane środowisko dla projektów CakePHP, w tym:

• Wstępnie zainstalowany interpreter PHP wraz z popularnymi rozszerzeniami.
• Zintegrowany menedżer pakietów Composer.
• Łatwe do konfiguracji serwery webowe (Caddy/Nginx).
• Wbudowane usługi bazodanowe (MySQL, PostgreSQL, Redis itd.).

Dzięki ServBay możesz uniknąć żmudnego procesu samodzielnej instalacji i konfiguracji wszystkich komponentów.

Wymagania wstępne

Przed rozpoczęciem prac upewnij się, że:

1. Zainstalowałeś ServBay: Pobierz i zainstaluj ServBay na swoim macOS.
2. Uruchomiłeś potrzebne usługi w ServBay: Otwórz aplikację ServBay i sprawdź, czy wymagane pakiety (np. PHP, wybrana baza danych — MySQL lub PostgreSQL, oraz system cache — Redis lub Memcached) są aktywne. Usługami zarządzasz w zakładce "Pakiety" panelu ServBay.
3. Znasz podstawy obsługi ServBay: Wiesz jak dodawać i konfigurować strony WWW. Jeśli nie, zajrzyj najpierw do Podstawowy przewodnik użytkowania ServBay.

Tworzenie projektu CakePHP

Rekomendujemy umieszczanie plików swoich projektów webowych w katalogu /Applications/ServBay/www — ułatwia to rozpoznawanie stron przez ServBay.

1. Otwórz Terminal

   Otwórz aplikację Terminal na macOS.

2. Przejdź do katalogu projektów ServBay

   Przenieś się do zalecanego przez ServBay katalogu na projekty:

   cd /Applications/ServBay/www

3. Utwórz katalog projektu

   Stwórz nowy podfolder na swój projekt CakePHP. W przykładzie użyjemy nazwy servbay-cakephp-app:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Stworzenie szkieletu projektu przez Composer

   Composer jest już preinstalowany w ServBay. Utwórz strukturę projektu CakePHP:

   composer create-project --prefer-dist cakephp/app .

   Komenda pobierze najnowszą, stabilną wersję CakePHP wraz ze wszystkimi zależnościami do bieżącego katalogu (.).

5. Instalacja sterownika ORM (jeśli używasz PostgreSQL)

   Jeśli wybierasz PostgreSQL jako bazę danych, doinstaluj sterownik ORM dla PostgreSQL:

   composer require cakephp/orm-pgsql

   W przypadku MySQL sterownik jest już zawarty w podstawowej paczce CakePHP.

Wstępna konfiguracja

Po utworzeniu projektu konieczna jest podstawowa konfiguracja — zwłaszcza połączenia z bazą danych.

1. Ustawienie zmiennych środowiskowych i połączenia z bazą

   Konfiguracja lokalnego środowiska (w tym danych do bazy) znajduje się w pliku config/app_local.php. Edytuj go i znajdź sekcję Datasources, gdzie uzupełnij dane dostępowe. Domyślne dane użytkownika w ServBay to zazwyczaj root oraz hasło password.

   Przykład konfiguracji bazy MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // lub \Cake\Database\Driver\Postgres::class dla PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // Adres bazy — domyślnie lokalnie
           //'port' => '3306', // Domyślny port MySQL: 3306, PostgreSQL: 5432
           'username' => 'root', // Domyślny użytkownik ServBay
           'password' => 'password', // Domyślne hasło ServBay
           'database' => 'servbay_cakephp_app', // Nazwa twojej bazy danych
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Ustaw identifier quoting na true, jeśli używasz np. "user" jako nazwy tabeli.
            * W przypadku nazw takich jak "cake" możesz zostawić false.
            * Jeśli nie jesteś pewien, ustaw true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Ograniczenia:
            * - Większość sterowników nie wspiera ustawiania poziomu izolacji przez PDO options.
            * - Nie wszystkie sterowniki obsługują wymuszanie kodowania znaków przez PDO.
            * - Opcje PDO nie są wspierane w sterownikach paczkowanych, jak Postgres w CakePHP.
            *   Dla Postgres wystarczy ustawić encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Jeśli korzystasz z DATABASE_URL, odblokuj tę linię
       ],
   ],

   Dostosuj driver oraz potencjalnie port zgodnie z używaną bazą danych oraz pilnuj spójności w nazwie bazy.

Konfiguracja serwera WWW (Tworzenie strony w ServBay)

By móc wejść na stronę projektu przez przeglądarkę, utwórz nową stronę w ServBay i wskaż folder projektu.

1. Otwórz panel ServBay

   Kliknij ikonę ServBay, aby uruchomić panel sterowania.

2. Przejdź do zakładki "Strony"

   W panelu wybierz zakładkę "Strony" (niegdyś "Hosty") po lewej.

3. Dodaj nową stronę

   Kliknij przycisk +, aby dodać nową stronę. Uzupełnij:

   • Nazwa: Rozpoznawalna nazwa, np. My CakePHP Dev Site.
   • Domena: Zdefiniowana nazwa domeny lokalnej, np. servbay-cakephp-test.local. ServBay automatycznie przypisze ją lokalnie.
   • Typ strony: Wybierz PHP.
   • Wersja PHP: Dopasowana do twojego CakePHP (np. CakePHP 4+ wymaga PHP 7.4+, CakePHP 5+ — minimum PHP 8.1), np. 8.3.
   • Katalog główny strony: UWAGA! Katalogiem głównym dla serwera WWW w CakePHP nie jest katalog projektu, lecz jego podkatalog webroot. Przykład: /Applications/ServBay/www/servbay-cakephp-app/webroot (zamień servbay-cakephp-app na aktualną nazwę katalogu projektu).

4. Zapisz i zastosuj zmiany

   Po skonfigurowaniu kliknij "Zapisz" w prawym dolnym rogu. Zatwierdź ostrzeżenie, by zastosować zmiany. ServBay automatycznie skonfiguruje serwer WWW (Caddy/Nginx), by domena servbay-cakephp-test.local wskazywała na folder webroot twojego projektu.

Szczegółowe kroki znajdziesz w dokumentacji ServBay, sekcja Dodawanie pierwszej strony.

Weryfikacja podstawowej konfiguracji

Możesz teraz wejść na swoją stronę przez przeglądarkę.

Otwórz przeglądarkę i wpisz skonfigurowaną domenę lokalną, np. https://servbay-cakephp-test.local.

Jeśli wszystko działa poprawnie, zobaczysz domyślną stronę powitalną CakePHP. To oznacza, że PHP, serwer WWW oraz konfiguracja strony w ServBay są prawidłowe.

Integracja bazy danych i cache

CakePHP umożliwia łatwe połączenie z bazą (MySQL/PostgreSQL) i systemami cache (Redis/Memcached) udostępnianymi przez ServBay.

Przykład relacyjnej bazy danych (MySQL / PostgreSQL)

Poniżej znajdziesz krok po kroku instrukcję połączenia CakePHP z bazą MySQL lub PostgreSQL, utworzenia prostej tabeli users oraz podstawowych operacji CRUD.

1. Utwórz bazę w ServBay

   Przed migracją bazy utwórz nową bazę danych w środowisku ServBay. Możesz użyć narzędzi jak phpMyAdmin (dla MySQL/MariaDB), pgAdmin (PostgreSQL) lub zewnętrznych narzędzi (Navicat, DBeaver). Łączysz się z adresem 127.0.0.1, użytkownik root, hasło password. Utwórz bazę servbay_cakephp_app.

2. Stwórz plik modelu ORM

   CakePHP wymaga pliku modelu ORM odpowiadającego za obsługę tabeli w bazie. Utwórz plik UsersTable.php dla tabeli users.

   Plik zapisz w src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Jeśli potrzebujesz walidacji
   
   class UsersTable extends Table
   {
       /**
        * Metoda inicjująca model
        *
        * @param array $config Konfiguracja tabeli
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Nazwa tabeli
           $this->setDisplayField('name'); // Domyślne pole widoczne przy powiązaniach
           $this->setPrimaryKey('id'); // Ustawienie klucza głównego
   
           // Jeśli chcesz automatyczne timestampy:
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Domyślne reguły walidacji.
        *
        * @param \Cake\Validation\Validator $validator Instancja walidatora.
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // Sprawdzenie unikalności email
   
           return $validator;
       }
   }

3. Utworzenie migracji przez Bake

   CakePHP rekomenduje używanie migracji do zarządzania bazą. W folderze głównym projektu (/Applications/ServBay/www/servbay-cakephp-app) uruchom:

   bin/cake bake migration CreateUsers name:string email:string:unique

   Komenda wygeneruje plik migracji z tabelą users i polami name (string) oraz email (string, unikalny).

4. Wykonaj migrację bazy

   Stwórz fizycznie tabelę poleceniem:

   bin/cake migrations migrate

   Po wykonaniu, nowa tabela będzie widoczna w twojej bazie danych.

5. Konfiguracja połączenia z bazą (jeśli jeszcze nie skonfigurowana)

   Upewnij się, że twój wpis Datasources.default w config/app_local.php odpowiada typowi i poświadczeniom do wybranej bazy.

   • Przykład konfiguracji dla MySQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // ... Pozostałe opcje
         ],
     ],

   • Przykład konfiguracji dla PostgreSQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // domyślny port
             'username' => 'root', // domyślny użytkownik ServBay
             'password' => 'password', // domyślne hasło ServBay
             'database' => 'servbay_cakephp_app',
             // ... Pozostałe opcje
         ],
     ],

6. Dodaj przykładowe routy i metody kontrolera

   Uzupełnij plik config/routes.php o trasy do obsługi bazy:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... inne trasy
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Przykładowa obsługa bazy
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... inne trasy
       $routes->fallbacks(DashedRoute::class);
   });

   Uzupełnij plik src/Controller/PagesController.php metodami do bazy danych:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Obsługa błędów zapytań
   
   class PagesController extends AppController
   {
       /**
        * Wyświetlanie widoku
        *
        * @param array ...$path Segmenty ścieżki.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... domyślna metoda display
           return new Response(['body' => 'Hello ServBay! This is the default page.']);
       }
   
       /**
        * Przykład bazy: dodanie użytkownika
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Pobranie modelu Users
   
           // Nowy użytkownik
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => '[email protected]' // Przykładowy e-mail ServBay
           ]);
   
           // Próba zapisania
           if ($usersTable->save($user)) {
               return new Response(['body' => 'User added successfully! User ID: ' . $user->id]);
           } else {
               // W razie niepowodzenia (np. błąd walidacji)
               $errors = $user->getErrors();
               return new Response(['body' => 'Failed to add user. Errors: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Przykład bazy: lista użytkowników
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Pobranie modelu Users
   
           // Pobierz wszystkich użytkowników
           $users = $usersTable->find()->all();
   
           // Zwróć wynik jako JSON
           return new Response(['body' => json_encode($users->toArray())]);
       }
   }

7. Odwiedź przykładowe adresy

   W przeglądarce:

   • Wejdź na https://servbay-cakephp-test.local/db-add-user, by dodać użytkownika (otrzymasz komunikat o sukcesie).
   • Wejdź na https://servbay-cakephp-test.local/db-list-users, by wyświetlić listę użytkowników (powinien pojawić się dodany przed chwilą).

W ten sposób skutecznie łączysz CakePHP z bazą w ServBay i wykonujesz operacje ORM.

Przykład systemu cache (Memcached / Redis)

CakePHP oferuje jednolite API cache, pozwalające płynnie przełączać się między silnikami (Memcached, Redis). ServBay ma wsparcie dla PHP-owych rozszerzeń oraz uruchamia odpowiednie usługi.

Najpierw upewnij się, że Memcached lub Redis działa w ServBay (panel — "Pakiety").

1. Konfiguracja połączenia z cache

   Edytuj plik config/app_local.php, sekcja Cache:

   • Przykład dla Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // Domyślnie w ServBay
             'prefix' => 'servbay_cakephp_',
         ],
         // ... Pozostałe konfiguracje cache
     ],

   • Przykład dla Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1',
             'port' => 6379,
             'password' => null, // W razie zastosowania hasła w Redis
             'database' => 0,
             'prefix' => 'servbay_cakephp_',
         ],
         // ... Pozostałe konfiguracje cache
     ],

   Dostosuj wedle używanego silnika.

2. Dodaj trasy i metody testowe cache

   Edytuj config/routes.php i dodaj nowe ścieżki:

   // config/routes.php
   // ... pozostałe trasy
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... pozostałe trasy

   Rozszerz kontroler Pages:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache;
   // ... pozostałe use
   
   class PagesController extends AppController
   {
       // ... metody display, dbAddUser, dbListUsers
   
       /**
        * Przykład cache: Memcached
        */
       public function cacheMemcached(): Response
       {
           // Upewnij się, że 'default' cache jest MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache miss
               $responseBody = 'Cache miss! Writing "Hello Memcached!" to cache.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Cache hit
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Przykład cache: Redis
        */
       public function cacheRedis(): Response
       {
           // Upewnij się, że 'default' cache jest RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Cache miss
               $responseBody = 'Cache miss! Writing "Hello Redis!" to cache.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Cache hit
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Testuj cache przez przeglądarkę

   Wejdź na:

   • https://servbay-cakephp-test.local/cache-memcached (test Memcached) — za pierwszym razem "Cache miss", po odświeżeniu "Cache hit".
   • https://servbay-cakephp-test.local/cache-redis (test Redis) — analogicznie.

Gotowe! Twój projekt wykorzystuje cache z ServBay.

Ważne wskazówki

• Dane dostępowe do bazy: Domyślne poświadczenia ServBay (root/password) są przeznaczone jedynie do użytku lokalnego. Na produkcji ustaw bezpieczne hasła!
• Katalog główny strony: Zawsze wskazuj webroot jako katalog główny strony w ServBay.
• Wersja PHP: Upewnij się, że wybrana wersja PHP w ServBay jest zgodna z wymaganiami twojego CakePHP (patrz dokumentacja CakePHP).
• Porty ServBay: Jeśli domyślne porty (80/443) są zajęte, zmień je w ustawieniach ServBay i popraw wpisy w systemowym pliku hosts lub uwzględnij port przy wchodzeniu na stronę.

Często zadawane pytania (FAQ)

• Q: Przy wejściu na servbay-cakephp-test.local pojawia się błąd "strona nie znaleziona"?
  • A: Sprawdź, czy katalog główny strony w ServBay poprawnie wskazuje na /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Upewnij się, że serwer WWW (Caddy/Nginx) ServBay działa.
  • Zweryfikuj wpis w pliku hosts — domena powinna być przypisana do 127.0.0.1 (ServBay robi to automatycznie, ale zawsze warto sprawdzić).
  • Sprawdź, czy pliki .htaccess lub konfiguracja serwera WWW nie zawierają błędów (w CakePHP domyślny plik webroot/.htaccess jest poprawny).
• Q: Problemy z połączeniem do bazy danych?
  • A: Sprawdź, czy wybrana usługa bazy (MySQL/PostgreSQL) działa w ServBay.
  • Upewnij się, że konfiguracja w config/app_local.php zawiera poprawne dane (host, port, username, password, database).
  • Zweryfikuj, czy baza danych servbay_cakephp_app faktycznie została utworzona.
• Q: Komendy Composer (bin/cake) nie działają?
  • A: Zwróć uwagę, by terminal był ustawiony w katalogu głównym projektu (/Applications/ServBay/www/servbay-cakephp-app).
  • Upewnij się, że pakiety PHP i Composer są aktywne w ServBay.
  • Sprawdź czy komenda php jest widoczna w konsoli (ServBay zwykle dodaje wpis do PATH, w razie problemów uruchom terminal z poziomu ServBay lub skonfiguruj ścieżki ręcznie).

Podsumowanie

ServBay znacząco upraszcza i przyspiesza proces tworzenia środowiska programistycznego CakePHP na macOS. Dzięki preinstalowanemu PHP, Composerowi, serwerom WWW oraz usługom bazodanowym konfiguracja ogranicza się do minimum. W tym artykule przeszedłeś przez cały proces — od stworzenia projektu, przez podstawową konfigurację i ustawienie serwera WWW, aż po integrację z relacyjną bazą danych oraz cache — co pozwoli szybko i wygodnie rozpocząć pracę nad aplikacją w CakePHP. Dzięki ServBay skupisz się na kodowaniu, a nie na żmudnych ustawieniach środowiska.