Создание и запуск проекта CakePHP в ServBay

ServBay — это локальная среда веб-разработки, специально разработанная для macOS. Она включает окружения для PHP, Node.js, Python, Go, Java и других языков, а также сервисы баз данных, такие как MySQL, PostgreSQL, MongoDB и Redis, в комплекте с веб-серверами Caddy или Nginx. Платформа обеспечивает удобство и эффективность для быстрого старта и управления локальными проектами.

В этом руководстве вы узнаете, как создать, настроить и запустить проект на CakePHP в среде ServBay. CakePHP — популярный PHP-фреймворк для веб-разработки, построенный по паттерну MVC (Модель-Представление-Контроллер) и известный своей скоростью разработки, мощным ORM и встроенными средствами безопасности. Благодаря удобству ServBay вы сможете очень быстро приступить к работе с CakePHP.

Что такое CakePHP?

CakePHP — это открытый фреймворк для разработки веб-приложений на PHP, предоставляющий структурную основу для быстрого и структурированного создания сайтов без потери гибкости. Он следует принципу "соглашение важнее конфигурации", что упрощает многие распространённые задачи разработки.

Основные возможности и преимущества CakePHP

• MVC-архитектура: Чёткая структура кода, простота поддержки и расширения.
• Быстрая разработка: CLI-инструмент (Bake) для генерации кода, существенно ускоряющий разработку.
• Мощный ORM: Простая работа с базами данных, поддержка разных СУБД.
• Встроенная безопасность: CSRF, защита от SQL-инъекций, валидация ввода и другие механизмы.
• Гибкий шаблонизатор: Работа с разными технологиями представления.
• Активное сообщество и плагины: Лёгкий поиск решений, множество расширений.
• Подробная документация: Детальные руководства и API-справочники.

CakePHP подходит для создания сайтов любого масштаба — от простых API до сложных корпоративных систем.

Настройка среды для разработки CakePHP в ServBay

ServBay предоставляет готовое интегрированное окружение для CakePHP, включая:

• Предустановленный интерпретатор PHP с необходимыми расширениями.
• Предустановленный менеджер пакетов Composer.
• Лёгкая настройка веб-сервера (Caddy/Nginx).
• Интегрированные сервисы баз данных (MySQL, PostgreSQL, Redis и др.)

С помощью ServBay вам не придётся самостоятельно заниматься рутиной установки и настройки этих компонентов.

Предварительные требования

Перед началом убедитесь, что выполнены следующие условия:

1. Установлен ServBay: Убедитесь, что вы скачали и успешно установили ServBay на macOS.
2. Запущены сервисы ServBay: Откройте приложение ServBay и запустите необходимые пакеты (например, PHP, требуемую базу данных - MySQL или PostgreSQL, а также кеширующие сервисы - Redis или Memcached). Управлять этими сервисами можно на вкладке «Пакеты» в панели управления ServBay.
3. Знакомство с основами работы ServBay: Убедитесь, что знаете, как добавлять и настраивать сайты в ServBay. Если нет — рекомендуем ознакомиться с Базовым руководством по ServBay.

Создание проекта CakePHP

Рекомендуется размещать web-проекты в каталоге /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. Создайте проект CakePHP с помощью Composer

   В ServBay Composer уже предустановлен. В каталоге проекта выполните команду генерации структуры проекта CakePHP:

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

   Эта команда скачает последнюю стабильную версию CakePHP и её зависимости в текущий каталог (.).

5. Установка ORM-драйвера (для PostgreSQL)

   Если вы планируете использовать PostgreSQL, установите ORM-драйвер для этой СУБД:

   composer require cakephp/orm-pgsql

   Для MySQL дополнительные драйверы обычно не требуются — они уже включены в зависимости фреймворка.

Базовая настройка

После создания проекта требуется базовая настройка — прежде всего подключение к базе данных.

1. Настройте переменные среды и соединение с базой данных

   Локальная конфигурация CakePHP находится в файле 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', // адрес сервера БД, по умолчанию локально
           //'port' => '3306', // порт по умолчанию MySQL 3306, PostgreSQL — 5432
           'username' => 'root',
           'password' => 'password',
           'database' => 'servbay_cakephp_app', // имя вашей БД
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Включайте идентификацию кавычками (quoteIdentifiers), если используете зарезервированные слова как имя таблицы.
            * Для "user" ставьте true, для "cake" можно оставить false.
            * Если не уверены, установите true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Ограничения:
            * - Большинство драйверов не поддерживают установку уровней изоляции через PDO-опции.
            *   При попытке использовать возникнет ошибка.
            * - Не все драйверы допускают установку кодировки через PDO-опции.
            * - Для Postgres достаточно настроить encoding, дополнительные PDO-опции не нужны.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // при использовании DATABASE_URL раскомментируйте
       ],
   ],

   Корректируйте driver и (при необходимости) port в зависимости от выбранной СУБД. Проверьте, чтобы имя базы совпадало со схемой вашей БД.

Настройка веб-сервера (создание сайта в ServBay)

Чтобы получить доступ к сайту через браузер, создайте в ServBay новый сайт, указав актуальный путь к проекту.

1. Откройте панель управления ServBay

   Щёлкните по иконке ServBay для открытия панели управления.

2. Перейдите на вкладку “Сайты”

   На левой панели выберите раздел «Сайты» (раньше — «Хосты»).

3. Добавьте новый сайт

   Нажмите на кнопку + для создания сайта. Заполните поля:

   • Имя: выберите читаемое название, например My CakePHP Dev Site.
   • Домен: укажите домен для локальной разработки, например servbay-cakephp-test.local (ServBay пропишет его в hosts).
   • Тип сайта: выберите PHP.
   • Версия PHP: укажите версию, подходящую вашему CakePHP (для CakePHP 4+ минимум PHP 7.4; для CakePHP 5+ нужен PHP 8.1 и выше, пример — 8.3).
   • Корневая папка сайта (Document Root): Внимание! Указывайте не корень проекта, а папку webroot внутри него: /Applications/ServBay/www/servbay-cakephp-app/webroot (замените servbay-cakephp-app на фактическое имя вашего каталога).

4. Сохраните и примените настройки

   После заполнения формы нажмите «Сохранить» и подтвердите внесение изменений. ServBay автоматически настроит веб-сервер (Caddy или Nginx) для обслуживания домена servbay-cakephp-test.local с папки webroot.

Отдельное подробное руководство по добавлению сайта доступно в разделе Добавление первого сайта.

Проверка начальных настроек

Теперь можно открыть сайт в браузере.

Откройте браузер и перейдите по адресу, который вы указали при создании сайта, например: https://servbay-cakephp-test.local.

Если всё настроено корректно, появится стандартная приветственная страница CakePHP — это значит, что PHP, веб-сервер и настройки сайта в ServBay работают корректно.

Интеграция баз данных и кеширования

В CakePHP реализованы мощные ORM и кеширующий слой, которые позволяют легко интегрировать СУБД и сервисы кеша, предоставляемые ServBay.

Работа с реляционными БД (MySQL / PostgreSQL)

Покажем, как с помощью CakePHP ORM соединиться с MySQL или PostgreSQL в ServBay, создать таблицу users и выполнять CRUD-операции.

1. Создайте БД в ServBay

   До миграции создайте новую базу servbay_cakephp_app через phpMyAdmin (для MySQL/MariaDB), pgAdmin (для PostgreSQL) или сторонние инструменты (Navicat, DBeaver), подключившись к сервису (127.0.0.1, user: root, password: password).

2. Создайте ORM-модель

   Для работы ORM требуется модель для таблицы. Создайте файл UsersTable.php:

   Сохраните следующий код в src/Model/Table/UsersTable.php:

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

   Для управления структурой БД рекомендуется использовать миграции. В корне проекта выполните:

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

   Команда сгенерирует миграцию для таблицы с полями name (строка) и email (строка, уникальный).

4. Примените миграцию

   Запустите миграцию для создания таблицы users:

   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',
             'password' => 'password',
             '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
       {
           // ... стандартный display-метод
           return new Response(['body' => 'Hello ServBay! This is the default page.']);
       }
   
       /**
        * Пример БД: Добавление пользователя
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('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 = $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 и провели базовые операции через ORM.

Пример интеграции кеширующих сервисов (Memcached/Redis)

В CakePHP используется единый API для кеширования, что позволяет быстро переключаться между Memcached и Redis. ServBay включает необходимые расширения для PHP и предоставляет соответствующие сервисы.

Убедитесь, что Memcached или Redis активированы во вкладке «Пакеты» в панели управления ServBay.

1. Настройте параметры кеша

   Откройте файл config/app_local.php и пропишите настройки в секции Cache.

   • Пример для Memcached:

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

   • Пример для Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1',
             'port' => 6379,
             'password' => null,
             'database' => 0,
             '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; // импорт Cache
   // ... другие use
   
   class PagesController extends AppController
   {
       // ... остальные методы (display, dbAddUser, dbListUsers)
   
       /**
        * Пример кеша: Memcached
        */
       public function cacheMemcached(): Response
       {
           // Убедитесь, что 'default' кеш сконфигурирован для 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' кеш сконфигурирован как 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.

Важные моменты

• Доступ к БД: Используйте стандартные учётные данные ServBay (root/password) только для локальной разработки. Для продуктивной среды обязательно задайте уникальные и безопасные параметры.
• Корень сайта: Всегда указывайте в настройках сайта ServBay в качестве Document Root — папку webroot из вашего проекта CakePHP, а не корневую директорию.
• Совместимость версий PHP: Следите, чтобы выбранная версия PHP в ServBay соответствовала требованиям используемой версии CakePHP. Уточняйте спецификации в официальной документации CakePHP.
• Порты ServBay: Если стандартные порты (80/443) заняты, смените их в настройках ServBay и, при необходимости, внесите изменения в hosts и используйте явное указание порта в браузере.

Часто задаваемые вопросы (FAQ)

• В: При переходе на servbay-cakephp-test.local выдаёт «страница не найдена»?
  • О: Проверьте, что Document Root в настройках сайта указывает на /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Удостоверьтесь, что веб-сервер (Caddy/Nginx) запущен.
  • Проверьте, что в hosts прописан домен servbay-cakephp-test.local на 127.0.0.1 (обычно ServBay настраивает автоматически, но иногда стоит проверить вручную).
  • Проверьте корректность файлов .htaccess или конфигурацию веб-сервера (обычно нужный .htaccess лежит в webroot и не требует правки).
• В: Не удаётся соединиться с базой данных?
  • О: Убедитесь, что выбранный сервис базы данных в ServBay (MySQL/PostgreSQL) работает.
  • Проверьте правильность настроек подключения в config/app_local.php (host, port, username, password, database) и наличие самой БД.
  • Убедитесь, что база данных servbay_cakephp_app действительно создана.
• В: Не выполняются команды Composer (bin/cake)?
  • О: Убедитесь, что ваша рабочая директория в терминале — корень проекта /Applications/ServBay/www/servbay-cakephp-app.
  • Проверьте, что пакеты PHP и Composer в ServBay запущены.
  • Проверьте, работает ли команда php в терминале (обычно ServBay добавляет её в PATH автоматически; при необходимости используйте терминал ServBay или настройте PATH вручную).

Заключение

ServBay позволяет быстро и эффективно развернуть локальную среду для разработки сайтов на CakePHP под macOS. Благодаря заранее интегрированным компонентам — PHP, Composer, веб-серверу и базам данных — установка и настройка максимально упрощены. В этом руководстве разобраны все этапы: от создания проекта и базовых настроек до подключения базы данных, настройки веб-сервера и интеграции кеширующих сервисов. Используя возможности ServBay, вы сможете сосредоточиться на программировании, полностью освободившись от рутинной настройки среды.