Створення та запуск проекту Phalcon

Що таке Phalcon?

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

Основні особливості та переваги Phalcon

Виняткова продуктивність: Phalcon працює як C-розширення, що уникає накладних витрат на парсинг PHP-скриптів і дає продуктивність, близьку до нативної.
Економія ресурсів: Вкрай низьке використання пам’яті — ідеальний вибір для застосунків з суворими вимогами до продуктивності та масштабованості.
Повний набір функцій: Містить більшість ключових компонентів для веб-розробки, зменшуючи залежність від сторонніх бібліотек.
Легкість у використанні: Чіткий та послідовний API і докладна документація дозволяють швидко освоїти Phalcon навіть новачкові.
Висока модульність: Компоненти можна використовувати окремо, обираючи лише необхідне для вашого проекту.
Безпека: Набір інструментів для фільтрації вводу, захисту від CSRF та інших аспектів безпеки.

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

Створення та запуск проекту Phalcon за допомогою ServBay

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

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

Передумови

Перед початком роботи переконайтеся, що виконані наступні умови:

ServBay встановлений і запущений: Перевірте, чи ServBay успішно встановлено і працює на вашій системі macOS.
Необхідна версія PHP активована: У ServBay переконайтесь, що обрана для проекту версія PHP увімкнена.
Модуль Phalcon активовано: У ServBay модуль Phalcon інтегровано, але він може бути вимкнений за замовчуванням. Не забудьте активувати розширення Phalcon для відповідної версії PHP, дотримуючись інструкцій з Як увімкнути модуль Phalcon у ServBay, і перезапустіть PHP-сервіс.
Composer встановлений: У ServBay вже інтегрований Composer, тому окремо встановлювати не потрібно. Переконайтеся, що команда composer доступна у вашому терміналі.

Сумісність версій Phalcon і DevTools

Необхідно обирати версію фреймворку Phalcon і супутніх інструментів розробника (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` (виправлена версія)	Рекомендується використовувати community-форк для кращої сумісності.

Важливо: Для PHP 8.x і новіших офіційний Phalcon DevTools може працювати некоректно. Рекомендуємо користуватися виправленою версією зі спільноти. Далі в інструкції наведено як встановити такий 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, виправлений fork): Оскільки офіційний DevTools може не працювати з PHP 8.x, скористаємося fork-репозиторієм зі спільноти:
  Створіть/відредагуйте composer.json у поточній директорії (/Applications/ServBay/www/servbay-phalcon-app):
  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 створить у папці проекту (servbay-phalcon-app) каталог vendor, а DevTools буде доступний як vendor/bin/phalcon.
Створіть каркас проекту через DevTools
Запустіть команду для генерації структури проекту. Всі вихідні файли будуть у підкаталозі (наприклад, теж servbay-phalcon-app, це типовий шаблон 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.

Налаштування оточення проекту

Головний файл з конфігураціями Phalcon-проекту — 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) у ServBay запущена, облікові дані співпадають із цим налаштуванням, а базу даних servbay_phalcon_app створено. Для керування БД можна використовувати phpMyAdmin чи Adminer з інтерфейсу ServBay.

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

Щоб мати доступ до проекту у браузері, потрібно створити сайт та привʼязати його до кореня вашого Phalcon-проекту.

Відкрийте програму ServBay
Перейдіть у розділ «Сайти»: У головному вікні натисніть на вкладку «Сайт».
Додайте новий сайт:
- Назва: Наприклад, My First Phalcon Dev Site.
- Домен: Наприклад, servbay-phalcon-test.local. ServBay автоматично сконфігурує .local для локального доступу.
- Тип сайту: Оберіть PHP.
- Версія PHP: Вкажіть версію з активованим модулем Phalcon.
- Корінь сайту: Дуже важливо! Точка входу Phalcon знаходиться у 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 (створіть, якщо його ще немає):

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

Покажемо, як підʼєднатися до MySQL у ServBay і виконати прості операції.

Створіть структуру БД (через міграції)

Міграції у Phalcon DevTools — стандартний спосіб керування версіями схеми БД.

Створіть міграцію: Виконайте у кодовому каталозі проекту:
bash
```
vendor/bin/phalcon migration generate
```
1
Це додасть файл до папки migrations, наприклад, YYYYMMDDHHMMSS_MigrationName.php.

Редагуйте міграцію: Відкрийте новий файл і в методі morph опишіть структуру простої таблиці users:

php

<?php

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

/**
 * Class UsersMigration_100
 */
class UsersMigration_100 extends Migration // Назва класу має співпадати з файлом
{
    /**
     * Run the migrations
     *
     * @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',
            ],
        ]);
    }

    /**
     * Reverse the migrations
     *
     * @return void
     */
    public function down()
    {
        // Опціонально: логіка для відкату міграції, наприклад, видалити таблицю
        // $this->getConnection()->dropTable('users');
    }
}

Зверніть увагу: Назва класу (наприклад, UsersMigration_100) має збігатися з іменем файлу, який створив DevTools.

Запустіть міграцію: Виконайте команду, щоб застосувати міграцію (створити таблицю):
bash
```
vendor/bin/phalcon migration run
```
1
Якщо отримуєте помилку з’єднання — перевірте налаштування БД у app/config/config.php та роботу служби MySQL/MariaDB у ServBay.

Перевірте підключення до БД (зроблено раніше)
Переконайтесь, що секція 'database' у app/config/config.php вказує на правильні параметри підключення.

Додайте маршрути для роботи з БД

В 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, додайте методи:

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', '[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);

        // 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 у сервісах Phalcon.

Встановлення розширення Redis
У більшості збірок PHP у ServBay розширення Redis вже встановлено. Переконайтеся, що воно увімкнене для обраної версії PHP.

Додайте налаштування Redis у конфігурацію

У app/config/config.php додайте секцію для Redis. За замовчуванням Redis слухає на 127.0.0.1:6379:

php

return new \Phalcon\Config([
    // ... інші налаштування ...
    'cache' => [
        'adapter' => 'Redis',
        'host' => '127.0.0.1',
        'port' => 6379,
        'index' => 0,
        'persistent' => false,
        'auth' => null, // вкажіть пароль, якщо потрібен
    ],
    // ... інші налаштування ...
]);

Додайте маршрут для тесту Redis

В 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 додайте метод для роботи з кешем Redis:

php

<?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' секцією у 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-контейнері для зручності використання по всій програмі.

Тестування
Відкрийте 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!".
- Надалі (у межах lifetime кешу) — "Data found in cache: " та "Data fetched from source: Hello Redis from ServBay!", що вказує на успішне зчитування з кешу.

Часті питання (FAQ)

Питання: Отримую 404 Not Found при відкритті сайту. Що робити?
- Відповідь: Перевірте, що в налаштуваннях сайту у ServBay в полі «Корінь сайту» прописано шлях до папки public вашого Phalcon-проекту (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Також переконайтесь, що обраний веб-сервер (Caddy чи Nginx) запущено, а домен локально прописано.
Питання: Помилка 'Class 'Phalcon\Mvc\Application' not found' або щось подібне під час запуску?
- Відповідь: Це зазвичай свідчить про неактивний Phalcon-модуль у PHP. Перейдіть у ServBay, активуйте розширення Phalcon для потрібної версії PHP і перезапустіть PHP. Детальніше — у розділі Як увімкнути модуль Phalcon у ServBay.
Питання: Не вдається зʼєднатися з базою даних. Що перевірити?
- Відповідь: Звірте у app/config/config.php параметри підключення (host, username, password, dbname). Переконайтесь, що потрібна СУБД у ServBay працює, користувач має права доступу й база створена.

Підсумки

ServBay максимально спрощує налаштування потужного локального середовища для розробки на Phalcon. Цей посібник охоплює створення каркасу проекту, налаштування веб-сервера, інтеграцію MySQL і Redis. Завдяки інтегрованим пакетам та зручному GUI ви сконцентруєтесь тільки на розробці додатку. Бажаємо успіхів із ServBay та Phalcon у створенні сучасних та ефективних веб-рішень!

Створення та запуск проекту Phalcon ​

Що таке Phalcon? ​

Основні особливості та переваги Phalcon ​

Створення та запуск проекту Phalcon за допомогою ServBay ​

Передумови ​

Сумісність версій Phalcon і DevTools ​

Створення проекту Phalcon ​

Налаштування оточення проекту ​

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

Додаємо приклад коду ​

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

Інтеграція з базою даних ​

Приклад роботи з реляційною БД: MySQL ​

Приклад з NoSQL: Redis ​

Часті питання (FAQ) ​

Підсумки ​