Создание и запуск проекта на Phalcon

Что такое Phalcon?

Phalcon — это открытый высокопроизводительный PHP-фреймворк, реализованный в виде расширения на C. Благодаря уникальной реализации Phalcon отличается крайне низким потреблением ресурсов и высокой скоростью выполнения, значительно опережая большинство традиционных PHP-фреймворков. Phalcon придерживается архитектурной модели MVC (модель-представление-контроллер) и предоставляет разработчикам богатый набор компонентов: ORM (объектно-реляционное отображение), шаблонизатор, маршрутизатор, кэширование, менеджер событий и другие. Его цель — помочь быстро создавать мощные и производительные веб-приложения и API.

Ключевые особенности и преимущества Phalcon

• Высокая производительность: Работая как расширение на C, Phalcon избегает расходов на парсинг и загрузку PHP-скриптов, обеспечивая производительность практически на уровне нативного кода.
• Эффективность использования ресурсов: Минимальное потребление оперативной памяти, подходит для приложений с высокими требованиями к производительности и масштабируемости.
• Широкий функционал: Встроены все основные компоненты, необходимые для разработки веб-приложений, минимизируя зависимость от сторонних библиотек.
• Простота использования: Четкий и последовательный API с отличной документацией позволяет даже новичкам быстро освоиться с Phalcon.
• Высокая модульность: Все компоненты спроектированы независимо, разработчик может использовать или заменять их по мере необходимости.
• Безопасность: В наличии целый набор инструментов для обеспечения безопасности, включая фильтрацию входных данных, защиту от CSRF и другие.

Phalcon — отличный выбор для построения высокопроизводительных и масштабируемых веб-приложений и API, особенно для проектов, где важна максимальная скорость и эффективное использование ресурсов.

Создание и запуск проекта на Phalcon с помощью ServBay

ServBay — это локальная среда для веб-разработки, специально разработанная для macOS. Она включает множество версий PHP, базы данных (MySQL, PostgreSQL, MongoDB, Redis) и веб-серверы (Caddy, Nginx, Apache), а также другие инструменты разработки. С ServBay легко создавать и управлять необходимой инфраструктурой для проектов на Phalcon.

В этом руководстве вы узнаете, как с помощью PHP-окружения ServBay создать базовый проект на Phalcon, настроить веб-сервер для доступа к нему и интегрировать реляционную базу данных (MySQL) и NoSQL-хранилище (Redis).

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

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

1. Установлен и запущен ServBay: ServBay должен быть успешно установлен и работать на вашем Mac.
2. Включена необходимая версия PHP: Проверьте, что нужная версия PHP активирована в ServBay.
3. Включен модуль Phalcon: Модуль Phalcon встроен в ServBay, но может быть выключен по умолчанию. Не забудьте включить его для соответствующей версии PHP, следуя инструкции Как включить встроенный модуль Phalcon в ServBay и перезагрузить PHP.
4. Доступен Composer: Composer уже включен в состав ServBay (подробнее), поэтому отдельная установка не требуется. Убедитесь, что команда composer доступна в терминале.

Совместимость разных версий Phalcon и DevTools

Версия фреймворка Phalcon и инструментов Phalcon DevTools должна соответствовать используемой версии PHP. В таблице ниже указано соответствие между основными версиями PHP, рекомендуемыми версиями Phalcon и DevTools:

Версия PHP	Рекомендуемая версия Phalcon	Рекомендуемая версия DevTools	Особенности
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1 (или 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (официальная)	Официальные DevTools могут работать нестабильно на PHP 8.x
PHP 8.3, 8.4	Phalcon 5.x	dev-master (фиксированная версия)	Рекомендуется использовать поддерживаемую комьюнити-редакцию для лучшей совместимости

Важно: Для PHP 8.x и выше совместимость официальных DevTools не гарантируется. Рекомендуется использовать фиксированные версии от комьюнити. В последующих шагах мы покажем, как подключать такие DevTools через Composer.

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

Рекомендуемый путь хранения сайтов

Для удобства все сайты и проекты рекомендуется размещать по адресу по умолчанию /Applications/ServBay/www. Демонстрация будет приведена с этим путём.

1. Перейдите в корневую папку сайтов и создайте папку проекта

   Откройте терминал и перейдите в основной каталог сайтов ServBay, затем создайте отдельную папку для нового проекта Phalcon (например, servbay-phalcon-app):

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. Установка Phalcon DevTools

   Phalcon DevTools — набор CLI-инструментов для быстрого генерации кода, начальной структуры проекта, миграций и многого другого. Устанавливать их будем через Composer. Команды зависят от используемой версии PHP:

   • Для PHP 5.6, 7.0, 7.1 (Phalcon DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • Для PHP 7.2, 7.3, 7.4 (Phalcon DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • Для PHP 8.0, 8.1, 8.2, 8.3, 8.4 (фремвор DevTools dev-master — фиксированная версия): Поскольку официальные DevTools могут некорректно работать с PHP 8.x, воспользуемся поддерживаемой сообществом версией. В корне проекта (/Applications/ServBay/www/servbay-phalcon-app) создайте или отредактируйте файл composer.json следующим образом:

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     После чего выполните обновление Composer для установки DevTools:

     composer update

   После установки Composer создаст папку vendor в корне проекта (servbay-phalcon-app), а исполняемый файл DevTools будет лежать по пути vendor/bin/phalcon.

3. Создайте структуру проекта с DevTools

   Генерируем базовые файлы проекта командой:

   vendor/bin/phalcon project servbay-phalcon-app

   Эта команда создаст в каталоге /Applications/ServBay/www/servbay-phalcon-app подпапку /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app со сгенерированной структурой Phalcon-проекта.

4. Перейдите в каталог с исходным кодом проекта

   Далее работаем уже в каталоге проекта:

   cd servbay-phalcon-app

   Сейчас текущая директория — /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Настройка окружения проекта

Основная конфигурация Phalcon-проекта содержится в файле app/config/config.php. В нём задаются параметры соединения с БД, пути и другие важные настройки.

1. Отредактируйте конфигурационный файл

   Откройте /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php в любимом редакторе кода. Найдите или добавьте секцию с настройками БД. В ServBay для MySQL/MariaDB по умолчанию пользователь — root, пароль пустой (по соображениям безопасности рекомендуется задать свой пароль!). В примере вместо пароля используется "password" — замените на свой. Имя базы данных (servbay_phalcon_app) также примерное — вы должны создать такую БД вручную.

   return new \Phalcon\Config([
       // ... другие настройки ...
       'database' => [
           'adapter' => 'Mysql', // или 'Postgres' и др.
           'host' => '127.0.0.1',
           'username' => 'root', // стандартный пользователь ServBay
           'password' => 'password', // <-- замените на ваш пароль
           'dbname' => 'servbay_phalcon_app', // <-- замените на имя вашей БД
       ],
       // ... другие настройки ...
   ]);

   Важно: Убедитесь, что необходимый сервис БД (MySQL/MariaDB) запущен в ServBay и данные пользователя совпадают с указанными в файле. Создайте базу данных вручную через phpMyAdmin или Adminer, доступные в ServBay.

Настройка веб-сервера (через функцию "Сайты" в ServBay)

Чтобы открыть свой проект в браузере, настройте веб-сайт через раздел Сайты в ServBay и укажите путь к папке с публичным доступом (public).

1. Откройте приложение ServBay
2. Перейдите к настройкам "Сайты": Найдите и нажмите соответствующую опцию на главном экране ServBay.
3. Добавьте новый сайт: Нажмите кнопку добавления.
   • Имя: Напишите, например, My First Phalcon Dev Site.
   • Домен: Укажите, как хотите обращаться к сайту, например, servbay-phalcon-test.local. ServBay автоматически настроит его на локальный адрес.
   • Тип сайта: Выберите PHP.
   • Версия PHP: Выберите ту, в которой включили модуль Phalcon.
   • Корневая директория: Важно! Файл index.php у Phalcon лежит в каталоге public, укажите полный путь: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Сохраните настройки: ServBay применит их и, при необходимости, перезапустит веб-сервер (Caddy или Nginx).

Подробности смотрите в разделе Добавление первого сайта. ServBay позаботится о настройке локального домена и нужной конфигурации веб-сервера.

Добавление тестового кода

Добавим немного кода, чтобы убедиться, что всё работает.

1. Настройте маршрутизацию

   Откройте /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php и пропишите простой маршрут для запросов к /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Определяем основной маршрут: при обращении к '/' запускается indexAction контроллера IndexController
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... здесь можно добавить другие маршруты ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Создайте контроллер

   Откройте /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php (или создайте, если файла нет), и добавьте метод indexAction:

   <?php
   namespace App\Controllers; // Проверьте правильность пространства имён
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Обрабатывает запросы к корню ('/')
       public function indexAction()
       {
           // Возвращает простую строку в ответе
           return 'Hello ServBay!';
       }
   }

Просмотр сайта

Сохраните изменения. Убедитесь, что ServBay запущен, и откройте браузер по адресу, который указали при настройке сайта:

https://servbay-phalcon-test.local

Если всё настроено верно, вы увидите текст Hello ServBay!.

Интеграция с базой данных

Phalcon предлагает мощный слой работы с БД и ORM. ServBay поддерживает несколько СУБД — их можно легко интегрировать с проектом на Phalcon. Рассмотрим на примере MySQL и Redis.

Пример с реляционной БД: MySQL

Покажем, как с помощью адаптера Phalcon подключиться к MySQL в ServBay и выполнить простую вставку и выборку.

1. Создайте структуру базы (используем миграции)

   DevTools поддерживают миграции для контроля версий структуры БД.

   • Сгенерируйте миграционный файл: В каталоге кода проекта выполните:

     vendor/bin/phalcon migration generate

     В папке migrations появится новый файл, например, YYYYMMDDHHMMSS_MigrationName.php.

   • Отредактируйте миграцию: Опишите структуру простой таблицы users в методе morph:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Имя класса должно совпадать с именем файла
     {
         /**
          * Выполнение миграции
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Откат миграции
          *
          * @return void
          */
         public function down()
         {
             // Необязательно: реализуйте, если нужен откат (например, удаление таблицы)
             // $this->getConnection()->dropTable('users');
         }
     }

     Примечание: Название класса (UsersMigration_100) должно совпадать с именем файла миграции.

   • Выполните миграцию: В каталоге кода проекта запустите команду, чтобы применить миграции и создать таблицу users:

     vendor/bin/phalcon migration run

     Если получите ошибку соединения — проверьте настройки БД в app/config/config.php и запущен ли сервис MySQL/MariaDB в ServBay.

2. Проверьте настройки БД (шаг уже выполнен выше)

   Убедитесь, что в секции 'database' файла app/config/config.php указан верный хост (127.0.0.1), порт (3306), пользователь (root), пароль и имя БД.

3. Добавьте маршруты для работы с БД

   В файле app/config/routes.php пропишите новые правила маршрутизации для добавления и просмотра пользователей:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Маршрут для добавления пользователя
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Маршрут для просмотра списка пользователей
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Реализуйте работу с БД в контроллере

   В файле app/controllers/IndexController.php добавьте методы mysqlAddAction и mysqlAction для выполнения операций с базой данных (в примере используется прямое создание подключения через адаптер Phalcon):

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Подключаем MySQL-адаптер
   use Phalcon\Db\Enum; // Константы для fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Добавление пользователя
       public function mysqlAddAction()
       {
           // Можно получить подключение через DI, либо создать вручную (как здесь)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- замените на ваш пароль
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4', // рекомендуется задать кодировку
           ]);
   
           // Вставляем запись
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', '[email protected]'],
               ['name', 'email']
           );
   
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Получение списка пользователей
       public function mysqlAction()
       {
            $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- замените на ваш пароль
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Примечание: В реальных приложениях рекомендуется вынести подключение к БД в сервис DI, чтобы не создавать соединение вручную каждый раз.

5. Проверьте функционал в браузере

   • Перейдите по адресу https://servbay-phalcon-test.local/mysql-add — при успехе увидите "User added successfully."
   • Затем откройте https://servbay-phalcon-test.local/mysql — увидите данные о пользователях в формате JSON.

Пример с NoSQL: Redis

Покажем использование Redis в проекте на Phalcon как кеширующего хранилища.

1. Проверьте наличие расширения Redis

   Как правило, PHP-пакеты от ServBay уже включают расширение Redis. Достаточно убедиться, что выбранная вами версия PHP в ServBay имеет Redis среди подключённых расширений.

2. Добавьте настройки соединения с Redis

   В файл app/config/config.php добавьте параметры для подключения к Redis (по умолчанию в ServBay это 127.0.0.1:6379):

   return new \Phalcon\Config([
       // ... другие настройки ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Номер базы Redis, по умолчанию 0
           'persistent' => false,
           'auth' => null, // если установлен пароль — укажите его здесь
       ],
       // ... другие настройки ...
   ]);

3. Добавьте пример маршрутизации для Redis

   Пропишите маршрут /redis в файле app/config/routes.php:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Добавляем маршрут для работы с Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Работа с Redis в контроллере

   В файле app/controllers/IndexController.php переходим к методу redisAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Redis-адаптер кеша
   use Phalcon\Storage\SerializerFactory; // Фабрика сериализации
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Пример использования кеша Redis
       public function redisAction()
       {
           // Создаём экземпляр фабрики сериализации
           $serializerFactory = new SerializerFactory();
   
           // Настройки кеша Redis
           // Важно: конфигурируйте согласно разделу 'cache' в app/config/config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'your_redis_password', // если установлен пароль
           ];
   
           // Создаём экземпляр Redis-кэша
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               echo "Data found in cache: ";
           }
   
           return $cachedData;
       }
   }

   Примечание: В боевых приложениях кеши обычно регистрируются как сервисы в DI для удобного повторного использования.

5. Проверьте работу Redis

   Откройте https://servbay-phalcon-test.local/redis в браузере.

   • Первый заход покажет "Data not found in cache, fetching from source...Data stored in cache." и "Data fetched from source: Hello Redis from ServBay!"
   • Повторный просмотр (пока не истёк TTL) — "Data found in cache: " и "Data fetched from source: Hello Redis from ServBay!", что говорит о получении данных из кеша.

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

• Q: При посещении сайта появляется ошибка 404 Not Found. Что делать?
  • A: Проверьте, что в настройках сайта ServBay верно указан путь к папке public вашего проекта (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Убедитесь, что веб-сервер Caddy или Nginx запущен и сработала локальная привязка домена.
• Q: Ошибка "Class 'Phalcon\Mvc\Application' not found" и подобные?
  • A: Не активировано расширение Phalcon для используемой версии PHP. Включите модуль Phalcon через интерфейс ServBay и перезапустите PHP. См. раздел Как включить встроенный модуль Phalcon в ServBay.
• Q: Не удаётся подключиться к базе данных.
  • A: Проверьте параметры базы данных в app/config/config.php (хост, имя пользователя, пароль, имя БД). Убедитесь, что MySQL запущен в ServBay и подключаемый пользователь имеет права доступа. База данных должна быть создана заранее.

Заключение

С помощью ServBay вы можете быстро развернуть высокопроизводительную локальную среду для работы с Phalcon. Данное руководство показало полный цикл — от создания структуры проекта, настройки сервера до интеграции с MySQL и Redis. Удобные инструменты и встроенные пакеты ServBay существенно сокращают время подготовки среды, позволяя сосредоточиться на непосредственной разработке Phalcon-приложений. Надеемся, что это руководство поможет вам успешно и продуктивно начать работу с ServBay и Phalcon!