Створення й запуск CakePHP-проєкту з ServBay

ServBay — це локальне середовище веб-розробки, спеціально створене для macOS. Воно містить підтримку багатьох мов програмування, таких як PHP, Node.js, Python, Go, Java, а також інтегровані сервіси баз даних на кшталт MySQL, PostgreSQL, MongoDB, Redis, у поєднанні із сучасними веб-серверами Caddy або Nginx. Завдяки ServBay розробники можуть швидко розгортати та управляти локальними проєктами без зайвих складнощів.

У цьому матеріалі ви дізнаєтеся, як створити, налаштувати та запустити CakePHP-проєкт у середовищі ServBay. CakePHP — популярний PHP-фреймворк для веб-розробки, побудований за патерном MVC (Model-View-Controller) та відомий своєю швидкістю, потужним ORM і захищеністю. Використовуючи можливості ServBay, ви зможете блискавично запустити розробку на CakePHP.

Що таке CakePHP?

CakePHP — це відкритий фреймворк для створення веб-додатків на PHP, що пропонує структуровану та швидку розробку без втрати гнучкості. В основі його ідеології лежить принцип “налаштувань менше — більше за домовленістю” (“convention over configuration”), тож багато рутинних задач у розробці автоматизуються.

Основні переваги та функції CakePHP

• MVC-архітектура: Чітка організація коду, простота підтримки та розширення.
• Швидка розробка: Command Line інструментарій (Bake) для генерації класів прискорює створення проєктів.
• Потужна ORM (Object-Relational Mapping): Легко працювати з даними в різних БД.
• Вбудований захист: Захист від CSRF, SQL-ін’єкцій, вбудована валідація даних та інші засоби безпеки.
• Гнучкий шаблонізатор: Підтримка різних шаблонних рішень та фреймворків подання.
• Активна спільнота і плагіни: Є підтримка, багато сторонніх розширень.
• Вичерпна документація: Гіди, довідники та референси API.

CakePHP підходить для проєктів будь-яких масштабів: від простих API до складних корпоративних систем.

Налаштування середовища розробки CakePHP із ServBay

ServBay створює оптимальне середовище для розробки на CakePHP, адже вже містить:

• Попередньо встановлений PHP із найпотрібнішими розширеннями.
• Вбудований менеджер пакетів Composer.
• Зручну конфігурацію веб-серверів (Caddy/Nginx).
• Інтегровані бази даних (MySQL, PostgreSQL, Redis тощо).

Вам не потрібно налаштовувати ці компоненти вручну — все вже зібрано в одному рішенні.

Перед початком роботи

Перед стартом перевірте, що зроблено наступне:

1. Встановлено ServBay: Завантажте й інсталюйте ServBay для macOS.
2. Запущено сервіс ServBay: Відкрийте додаток ServBay і переконайтеся, що необхідні пакети (наприклад, PHP, вибрана база даних: MySQL або PostgreSQL, а також кеш-сервіси Redis або Memcached) вже працюють. Всі сервіси можна керувати через вкладку “Пакети” (“Packages”) у панелі ServBay.
3. Ознайомлення з базовими принципами роботи з ServBay: Важливо знати, як додавати та налаштовувати веб-сайти в ServBay. Якщо це вперше — радимо спочатку проглянути Базовий гід з використання ServBay.

Створення проєкту CakePHP

Рекомендується зберігати всі файли веб-проєктів у каталозі /Applications/ServBay/www. Це дозволяє ServBay автоматично знаходити та управляти вашими сайтами.

1. Відкрийте Термінал

   Запустіть стандартний додаток “Термінал” у macOS.

2. Перейдіть у каталог сайтів ServBay

   Перейдіть у папку для зберігання сайтів:

   cd /Applications/ServBay/www

3. Створіть каталог для проєкту

   Створіть нову папку для вашого CakePHP-проєкту, наприклад, servbay-cakephp-app:

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

4. Створіть “скелет” проєкту за допомогою Composer

   Composer вже встановлений у ServBay. Створіть новий проєкт у поточному каталозі:

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

   Ця команда завантажить і встановить останню стабільну версію CakePHP із усіма залежностями у поточну папку (.).

5. Встановіть ORM-драйвер для PostgreSQL (якщо потрібно)

   Якщо використовуєте PostgreSQL, встановіть додатковий драйвер:

   composer require cakephp/orm-pgsql

   Для MySQL усе необхідне вже входить до основних залежностей CakePHP.

Початкове налаштування

Після створення проєкту потрібно налаштувати ключові параметри — особливо, підключення до бази даних.

1. Налаштуйте змінні оточення й доступ до бази даних

   Всі налаштування для локальної розробки знаходяться у config/app_local.php. Відкрийте цей файл, знайдіть секцію Datasources і внесіть дані для вашої СУБД. Типові значення для ServBay: ім’я користувача root, пароль password.

   Приклад конфігурації для MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // або \Cake\Database\Driver\Postgres::class для PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // Хост для бази; у ServBay все локально
           //'port' => '3306', // Типовий порт MySQL — 3306, для PostgreSQL — 5432
           'username' => 'root', // Стандартне ім’я користувача ServBay
           'password' => 'password', // Стандартний пароль ServBay
           'database' => 'servbay_cakephp_app', // Назва вашої БД
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Встановіть true, якщо у вас таблиця з іменем, наприклад, "user".
            * Якщо імена звичайні, то можна лишити false.
            * Якщо не впевнені — залиште true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Обмеження:
            * - Більшість драйверів не підтримує налаштування рівнів ізоляції через PDO.
            * - Не всі драйвери підтримують налаштування кодування через PDO.
            * - Для драйверів-пакетів (напр. Postgres CakePHP) достатньо вказати кодування.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Якщо ви використовуєте DATABASE_URL, розкоментуйте цей рядок
       ],
   ],

   В залежності від вашої СУБД (MySQL/PostgreSQL), налаштуйте відповідно драйвер і порт. Переконайтеся, що назва бази даних збігається із фактичною у вашому середовищі.

Налаштування веб-сервера (створення сайту в ServBay)

Щоб мати змогу відкривати CakePHP-проєкт у браузері, потрібно налаштувати сайт у ServBay так, щоб його кореневий каталог вказував на ваш проєкт.

1. Відкрийте панель керування ServBay

   Клікніть на іконку ServBay для відкриття панелі керування.

2. Перейдіть до вкладки “Веб-сайти”

   У лівому меню виберіть “Веб-сайти” (“Websites”, колись — “Hosts”).

3. Додайте новий сайт

   Натисніть + внизу для створення нового сайту та введіть такі дані:

   • Ім’я (Name): Наприклад, My CakePHP Dev Site.
   • Домен (Domain): Локальний домен, наприклад, servbay-cakephp-test.local (ServBay автоматично налаштує під це).
   • Тип сайту (Site Type): Вибирайте PHP.
   • Версія PHP (PHP Version): Сумісна версія (CakePHP 4+ — PHP 7.4+, CakePHP 5+ — PHP 8.1+). Наприклад, 8.3.
   • Коренева папка сайту (Document Root): Увага! Для CakePHP це не основний каталог проєкту, а підкаталог webroot: /Applications/ServBay/www/servbay-cakephp-app/webroot (замініть servbay-cakephp-app на фактичну назву вашої папки).

4. Збережіть і застосуйте зміни

   Після заповнення форм натисніть “Зберегти”. Підтвердіть застосування змін — ServBay автоматично сконфігурує веб-сервер для вашого доменного імені (servbay-cakephp-test.local) та направить всі запити у папку webroot вашого проєкту.

Детальний процес створення сайту можна переглянути у розділі Додавання першого сайту документації ServBay.

Перевірка роботи проєкту

Тепер ви можете відкрити сайт у браузері.

Перейдіть до налаштованого вами домену, наприклад, https://servbay-cakephp-test.local.

Якщо всі налаштування правильні, ви побачите стандартну welcome-сторінку CakePHP — це сигнал, що PHP, веб-сервер і налаштування ServBay працюють коректно.

Інтеграція бази даних і кешу

CakePHP підтримує розширену ORM і кешування, що дозволяє легко підключатися до баз даних та кеш-сервісів, які вже входять до складу ServBay.

Приклад роботи з реляційною БД (MySQL / PostgreSQL)

Покроково підключимо ORM CakePHP до MySQL або PostgreSQL, створимо таблицю users та реалізуємо стандартні CRUD-операції.

1. Створіть базу даних у ServBay

   Перед застосуванням міграцій створіть потрібну БД. Скористайтеся графічними інструментами, наприклад, phpMyAdmin для MySQL/MariaDB, pgAdmin для PostgreSQL або сторонніми (Navicat, DBeaver тощо). Підключайтеся до хоста 127.0.0.1 з логіном root та паролем password. Створіть базу з назвою servbay_cakephp_app.

2. Створіть модель ORM

   CakePHP для взаємодії з таблицею використовує Model-файл. Створіть UsersTable.php у src/Model/Table/:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Якщо потрібна валідація
   
   class UsersTable extends Table
   {
       /**
        * Метод ініціалізації
        *
        * @param array $config Конфігурація Table.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Вказати ім’я таблиці
           $this->setDisplayField('name'); // Поле для відображення за замовчуванням (напр. у асоціаціях)
           $this->setPrimaryKey('id'); // Первинний ключ
   
           // Якщо потрібно автоматично вести часові мітки
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Дефолтні правила валідації.
        *
        * @param \Cake\Validation\Validator $validator Екземпляр Validator.
        * @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']); // Унікальний email
   
           return $validator;
       }
   }

3. Згенеруйте файл міграції через Bake

   Для керування схемою БД в CakePHP використовуються міграції. У корені проєкту (/Applications/ServBay/www/servbay-cakephp-app) виконайте:

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

   Це сформує міграцію для створення таблиці users із полями name (рядок) та email (унікальне поле).

4. Застосуйте міграцію

   Запустіть застосування міграції:

   bin/cake migrations migrate

   Після успішного виконання вказана таблиця з’явиться у вашій БД.

5. Перевірте налаштування підключення до БД

   Упевніться, що у config/app_local.php секція Datasources.default вказана правильно (тип, користувач, пароль, база).

   • 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',
             // ... решта налаштувань
         ],
     ],

   • PostgreSQL (приклад):

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // Типовий порт
             'username' => 'root', // ServBay за замовчуванням
             'password' => 'password', // ServBay за замовчуванням
             'database' => 'servbay_cakephp_app',
             // ... решта налаштувань
         ],
     ],

6. Додайте маршрути та екшени контролера

   У config/routes.php додайте маршрути для додавання користувача й перегляду списку:

   // 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) {
       // ... інші маршрути
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Демо-маршрути для БД
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... решта
       $routes->fallbacks(DashedRoute::class);
   });

   Далі у src/Controller/PagesController.php додайте нові методи:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Для обробки винятків при пошуку
   
   class PagesController extends AppController
   {
       /**
        * Відображення сторінки
        *
        * @param array ...$path Сегменти шляху.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // Стандартний метод
           return new Response(['body' => 'Hello ServBay! This is the default page.']);
       }
   
       /**
        * Демо взаємодії з БД: додати користувача
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Таблиця Users
   
           // Новий користувач
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => '[email protected]' // демо email
           ]);
   
           // Спроба збереження
           if ($usersTable->save($user)) {
               return new Response(['body' => 'User added successfully! User ID: ' . $user->id]);
           } else {
               // Помилки валідації тощо
               $errors = $user->getErrors();
               return new Response(['body' => 'Failed to add user. Errors: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Демо взаємодії з БД: перелік користувачів
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Таблиця Users
   
           // Всі користувачі
           $users = $usersTable->find()->all();
   
           // Виведення JSON
           return new Response(['body' => json_encode($users->toArray())]);
       }
   }

7. Перевірка роботи прикладу з БД

   Відкрийте браузер:

   • Перейдіть на https://servbay-cakephp-test.local/db-add-user — додасть нового користувача і виведе повідомлення про успіх.
   • Перейдіть на https://servbay-cakephp-test.local/db-list-users — бачите весь список користувачів у БД.

Ваш CakePHP-проєкт тепер інтегровано з реляційною СУБД у ServBay, CRUD-операції працюють.

Приклад кешування (Memcached / Redis)

CakePHP має абстракцію кешу, що дозволяє швидко змінювати рушій: Memcached чи Redis. У ServBay вже встановлені потрібні PHP-розширення й сервіси.

Перед початком переконайтеся, що у вкладці “Пакети” панелі керування ServBay запущено відповідний сервіс (Memcached або Redis).

1. Налаштування кеша

   Відредагуйте секцію Cache у config/app_local.php, вказавши потрібний кеш-рушій.

   • Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // Адреса й порт Memcached
             'prefix' => 'servbay_cakephp_', // Префікс ключів
         ],
         // ... інші налаштування кеша
     ],

   • Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // Адреса Redis
             'port' => 6379, // Порт Redis
             'password' => null, // У разі потреби можна вказати пароль
             'database' => 0, // Індекс БД Redis
             'prefix' => 'servbay_cakephp_', // Префікс ключів
         ],
         // ... інші налаштування кеша
     ],

   Оберіть потрібний сервіс та збережіть файл.

2. Додайте маршрути та контролери для кешу

   У config/routes.php додайте:

   // config/routes.php
   // ... решта
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... решта

   У src/Controller/PagesController.php додайте методи для прикладів:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache;
   // ... решта use
   
   class PagesController extends AppController
   {
       // ... інші методи
   
       /**
        * Демонстрація кешу: Memcached
        */
       public function cacheMemcached(): Response
       {
           // Переконайтеся, що 'default' у app_local.php — це MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey); // Спроба зчитати з кешу
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Кеш не містить значення
               $responseBody = 'Cache miss! Writing "Hello Memcached!" to cache.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Кешована відповідь
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Демонстрація кешу: Redis
        */
       public function cacheRedis(): Response
       {
            // 'default' у app_local.php — RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               $responseBody = 'Cache miss! Writing "Hello Redis!" to cache.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               $responseBody = 'Cache hit! Data from cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Перевірка роботи кешу

   Відкрийте браузер:

   • Для Memcached: https://servbay-cakephp-test.local/cache-memcached — перший раз буде “Cache miss”, повторно — “Cache hit”.
   • Для Redis: https://servbay-cakephp-test.local/cache-redis — аналогічно.

Це означає, що ваш CakePHP-проєкт коректно використовує кеш-рушії ServBay.

Важливі зауваження

• Доступ до СУБД: Стандартні креденціали (root/password) призначені лише для локальної розробки! Для продакшену створюйте окремих користувачів із складними паролями.
• Коренева папка сайту: Обов’язково вказуйте корінь сайту саме як webroot у проєкті CakePHP, а не основну папку — це рекомендований підхід.
• Сумісність PHP: Перевіряйте, щоб обрана у ServBay версія PHP відповідала вимогам вашого релізу CakePHP. Дивіться офіційну документацію CakePHP.
• Порти ServBay: Якщо за замовчуванням порти (80/443) зайняті, змініть їх у налаштуваннях ServBay і, якщо потрібно, відкоригуйте hosts або використовуйте порт у URL.

Поширені питання (FAQ)

• Q: Чому при переході на servbay-cakephp-test.local пише “Сторінку не знайдено”?
  • A: Перевірте, що корінь сайту у ServBay — саме /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Перевірте, що веб-сервери (Caddy/Nginx) у ServBay запущені.
  • Перевірте, що в hosts присутній запис, який відправляє servbay-cakephp-test.local на 127.0.0.1 (ServBay робить це автоматично, але інколи варто пересвідчитись).
  • Перевірте, чи налаштовано файл .htaccess у webroot або відповідна конфігурація веб-сервера.
• Q: Не вдається з’єднатися з базою даних?
  • A: Переконайтеся, що вибрана база даних (MySQL/PostgreSQL) запущена у ServBay.
  • Перевірте правильність параметрів підключення у config/app_local.php (host, port, username, password, database).
  • Переконайтеся, що база servbay_cakephp_app вже створена.
• Q: Не працюють команди Composer (bin/cake)?
  • A: Перевірте, що ви у кореневій папці CakePHP-проєкту (/Applications/ServBay/www/servbay-cakephp-app).
  • Переконайтеся, що PHP і Composer запущені в ServBay (“Пакети”).
  • Подивіться, чи термінал бачить команду php (ServBay зазвичай додає PHP у PATH). За потреби використовуйте інтегрований термінал ServBay або налаштуйте PATH вручну.

Висновок

Завдяки ServBay ви можете швидко та без складних налаштувань створити повноцінне локальне середовище для розробки проєктів на CakePHP у macOS. Вбудовані PHP, Composer, веб-сервер і сервіси баз даних максимально спрощують процес конфігурації. Дотримуючись наведених у цьому матеріалі інструкцій — від встановлення до інтеграції з базами даних і кешем — ви зможете швидко почати роботу з CakePHP, зосередившись на розробці, а не на рутинних установках і налаштуваннях.