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

Что такое Phalcon?

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

Основные особенности и преимущества Phalcon

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

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

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

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

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

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

Перед началом убедитесь, что:

ServBay установлен и запущен: Убедитесь, что ServBay успешно установлен и работает на macOS.
Нужная версия PHP включена: В ServBay активируйте необходимую версию PHP для проекта.
Модуль Phalcon включён: ServBay поставляется с модулем Phalcon, но он может быть отключён по умолчанию. Включите нужное расширение для вашей версии PHP по инструкции из Как включить модуль Phalcon в ServBay, затем перезапустите PHP.
Composer доступен: В ServBay уже предустановлен Composer — отдельная установка не требуется. Проверьте возможность использовать команду composer в терминале.

Соответствие версий Phalcon и DevTools

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

Версия 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 от сообщества, поскольку официальная версия может работать некорректно. В дальнейших шагах будет приведён способ установки такого варианта через Composer.

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

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

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

Перейдите в папку и создайте директорию для проекта
Откройте терминал, перейдите в корневую папку сайтов ServBay и создайте новую папку для вашего проекта Phalcon (например, servbay-phalcon-app):
bash
```
cd /Applications/ServBay/www
mkdir servbay-phalcon-app
cd servbay-phalcon-app
```
1
2
3
Установка Phalcon DevTools
Phalcon DevTools — это набор CLI-инструментов для быстрой генерации кода, создания "скелета" проекта, управления миграциями и прочего. Установка производится через Composer, в зависимости от нужной версии PHP:
- Для PHP 5.6, 7.0, 7.1 (Phalcon DevTools ^3.4):
  bash
```
composer require phalcon/devtools:"^3.4"
```
  1
- Для PHP 7.2, 7.3, 7.4 (Phalcon DevTools ~4.1):
  bash
```
composer require phalcon/devtools:"~4.1"
```
  1
- Для PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools dev-master, исправленная версия):
  Поскольку официальная версия DevTools может работать некорректно с PHP 8.x, используйте исправленный вариант от сообщества. В корне вашего проекта (/Applications/ServBay/www/servbay-phalcon-app) создайте или отредактируйте файл composer.json с таким содержанием:
  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
}
```
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  После этого выполните команду для установки:
  bash
```
composer update
```
  1
После установки Composer создаст папку vendor в корне (servbay-phalcon-app), исполняемый файл DevTools — vendor/bin/phalcon.
Генерация каркаса проекта с помощью DevTools
Используйте установленную команду DevTools для создания базовой структуры проекта. Код будет размещён в дополнительной вложенной папке (например, с тем же именем), что соответствует поведению DevTools по умолчанию:
bash
```
vendor/bin/phalcon project servbay-phalcon-app
```
1
Этот шаг создаст подкаталог /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app с готовым каркасом проекта на Phalcon.
Перейдите в папку с кодом проекта
Во всех дальнейших инструкциях используйте директорию проекта:
bash
```
cd servbay-phalcon-app
```
1
Теперь вы находитесь в /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

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

Конфигурирование обычно происходит в файле app/config/config.php, где задаются параметры подключения к БД, пути приложения и другие важные настройки.

Отредактируйте конфиг
Откройте файл /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php любым редактором. Найдите секцию базы данных или добавьте её. В ServBay для MySQL/MariaDB по умолчанию используется пользователь root и пустой пароль, однако настоятельно рекомендуем установить надёжный пароль. В примере показан пароль password — замените его на свой. Имя базы, например, servbay_phalcon_app, вам потребуется создать вручную.
php
```
return new \Phalcon\Config([
    // ... другие настройки ...
    'database' => [
        'adapter' => 'Mysql', // можно заменить на 'Postgres' или другую СУБД
        'host' => '127.0.0.1',
        'username' => 'root', // пользователь по умолчанию в ServBay
        'password' => 'password', // <-- замените на ваш пароль
        'dbname' => 'servbay_phalcon_app', // <-- замените на вашу базу данных
    ],
    // ... другие настройки ...
]);
```
1
2
3
4
5
6
7
8
9
10
11
Важно: Проверьте, что соответствующая база данных уже создана, а сервис запущен (MySQL/MariaDB). Для создания базы и управления пользователями используйте phpMyAdmin, Adminer или другой инструмент в ServBay.

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

Чтобы иметь доступ к проекту через браузер, используйте функцию Сайт в ServBay — настройте виртуальный хост, который будет указывать на папку public вашего проекта.

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

Подробную инструкцию смотрите Добавление первого сайта. ServBay автоматически настроит разрешение домена и все необходимые параметры веб-сервера.

Добавление примера кода

Давайте напишем простой пример для проверки работоспособности проекта.

Настройка маршрутов

В файле /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php добавьте базовое правило для корневого адреса /:

php

<?php
use Phalcon\Mvc\Router;

$router = new Router(false);

// Определяем основной маршрут, связываем '/' с IndexController и indexAction
$router->add(
    '/',
    [
        'controller' => 'index',
        'action'     => 'index',
    ]
);

// ... другие маршруты по мере необходимости ...

$router->handle($_SERVER['REQUEST_URI']);

return $router;

Создание контроллера

В файле /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php создайте или дополните класс с методом indexAction:

php

<?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, выполнить простые операции вставки и выборки.

Создание структуры базы (миграции)

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

Сгенерируйте файл миграции: Из директории проекта (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app):
bash
```
vendor/bin/phalcon migration generate
```
1
Будет создан файл миграции в папке migrations, например, YYYYMMDDHHMMSS_MigrationName.php.

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

php

<?php

use Phalcon\Db\Column;
use Phalcon\Db\Index;
use Phalcon\Migrations\Mvc\Model\Migration;

/**
 * Класс 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) соответствует имени файла миграции.

Выполните миграцию: В директории проекта:
bash
```
vendor/bin/phalcon migration run
```
1
При ошибках подключения проверьте конфиг базы (app/config/config.php) и работу сервиса MySQL/MariaDB в ServBay.

Настройка подключения к базе (предварительно уже выполнено)
Проверьте параметры 'database' в app/config/config.php — они должны соответствовать вашему сервису MySQL/MariaDB (обычно host — 127.0.0.1, порт 3306, пользователь root, пароль и имя БД — согласно вашим настройкам).

Добавление новых маршрутов

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

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;

Реализация методов работы с БД в контроллере

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

php

<?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', 'demo@servbay.test'],
            ['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);

        // JSON-вывод
        header('Content-Type: application/json');
        echo json_encode($users);
    }
}

Примечание: На практике стоит регистрировать подключение к базе в контейнере сервисов и использовать DI.

Проверка работы
- Откройте браузер: https://servbay-phalcon-test.local/mysql-add — при успехе увидеть "User added successfully."
- Перейдите по адресу https://servbay-phalcon-test.local/mysql — увидите JSON с содержимым таблицы users, включая тестовую запись.

Пример: база данных NoSQL Redis

Покажем, как подключиться к Redis через ServBay и использовать кеширование.

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

Настройка подключения к Redis

Вкладку 'cache' добавьте в app/config/config.php:

php

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

Добавьте маршрут для примера кеша

В app/config/routes.php, добавьте путь:

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;

Использование Redis в контроллере

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

php

<?php
namespace App\Controllers;

use Phalcon\Mvc\Controller;
use Phalcon\Db\Adapter\Pdo\Mysql;
use Phalcon\Db\Enum;
use Phalcon\Cache\Adapter\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();

        // Настройки соответствуют config.php
        $options = [
            'defaultSerializer' => 'Json',
            'lifetime'          => 3600,
            'host'              => '127.0.0.1',
            'port'              => 6379,
            'index'             => 0,
            // 'auth'           => 'your_redis_password', // если нужен пароль
        ];

        // Экземпляр кеша
        $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 и использовать их через контейнер.

Проверка работы
Перейдите на 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!".
- Повторные загрузки (пока кеш не истечёт): "Data found in cache: " и "Data fetched from source: Hello Redis from ServBay!" — данные получены из Redis.

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

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

Заключение

Используя ServBay, вы сможете с лёгкостью развернуть локальное окружение для разработки на Phalcon, обладающее высокой производительностью. В этом руководстве был рассмотрен процесс создания скелета проекта, настройки веб-сервера, а также интеграции MySQL и Redis. Благодаря интеграции различных инструментов и удобному интерфейсу ServBay настройка и поддержка среды разработки становится максимально простой, а вы можете сконцентрироваться на задачи и развитии вашего приложения. Надеемся, что данное руководство поможет вам начать продуктивную работу с Phalcon и ServBay для быстрой веб-разработки!

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

Что такое Phalcon? ​

Основные особенности и преимущества Phalcon ​

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

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

Соответствие версий Phalcon и DevTools ​

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

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

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

Добавление примера кода ​

Доступ к сайту ​

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

Пример: реляционная база MySQL ​

Пример: база данных NoSQL Redis ​

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

Заключение ​