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

Що таке Phalcon?

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

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

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

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

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

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

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

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

Перед стартом переконайтеся, що:

1. ServBay встановлений та запущений: Переконайтесь, що ServBay встановлений і працює на вашому Mac.
2. Обрана PHP-версія активована: У ServBay переконайтеся, що потрібна вам версія PHP включена.
3. Модуль Phalcon активовано: Модуль Phalcon вже міститься у ServBay, але може бути неактивним за замовчуванням. Активуйте відповідний модуль згідно інструкції з активації Phalcon в ServBay і перезавантажте PHP.
4. Composer доступний: Composer включений у ServBay за замовчуванням (деталі про Composer тут), додатково встановлювати не треба. Переконайтеся, що команда composer доступна у терміналі.

Вибір версії Phalcon та DevTools

Важливо узгодити версію фреймворка Phalcon і DevTools з вашою PHP-версією. У таблиці нижче наведено відповідність популярних версій PHP, Phalcon та DevTools:

Версія PHP	Рекомендована версія Phalcon	Рекомендована версія 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 (фіксований репозиторій)	Радимо використовувати виправлену версію DevTools від спільноти для кращої сумісності

Увага: Для PHP 8.x і новіше офіційні DevTools можуть не працювати коректно. Радимо використовувати виправлену версію, з інсталяцією якої допоможе Composer. Нижче детально описано процес.

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

Рекомендований шлях для проектів

Для зручності ServBay радить зберігати усі веб-проекти у стандартній директорії /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 (DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • Для PHP 8.0 і вище (DevTools dev-master, виправлена версія): Оскільки офіційні DevTools можуть некоректно працювати з PHP 8.x, використовуйте виправлений репозиторій від спільноти. Створіть чи відредагуйте composer.json у корені (/Applications/ServBay/www/servbay-phalcon-app) так:

     {
        "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:

     composer update

   Після цього у директорії проекту (servbay-phalcon-app) з’явиться папка vendor, а виконуваний файл DevTools буде у vendor/bin/phalcon.

3. Створення каркасу проекту через DevTools

   Запустіть команду для генерації базової структури Phalcon-проекту (код буде у підпапці, наприклад, servbay-phalcon-app — це дефолтне ім’я):

   vendor/bin/phalcon project servbay-phalcon-app

   В результаті буде створено піддиректорію /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app, з базовим каркасом проекту.

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)

Щоб перейти до сайту у браузері, потрібно налаштувати віртуальний хост та вказати правильну папку для проекту.

1. Відкрийте додаток ServBay
2. Перейдіть в налаштування «Сайти»: Знайдіть та відкрийте розділ «Сайти» у головному меню ServBay.
3. Додайте новий сайт:
   • Назва: Задайте зрозумілу назву, наприклад, My First Phalcon Dev Site.
   • Домен: Вкажіть домен для локального доступу, наприклад, servbay-phalcon-test.local (ServBay автоматично підключає домени з .local).
   • Тип сайту: Оберіть PHP.
   • Версія PHP: Виберіть PHP-версію, для якої активовано Phalcon.
   • Коренева папка сайту: Це важливо! 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);
   
   // Визначаємо дефолтний роут: '/' перенаправляє до IndexController, indexAction
   $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

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

1. Створення структури БД (через міграції)

   DevTools підтримує міграції — зручний спосіб версіонування структури бази даних.

   • Генерація файлу міграції: У папці проекту (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app) зробіть міграцію:

     vendor/bin/phalcon migration generate

     У каталозі migrations створиться файл типу YYYYMMDDHHMMSS_MigrationName.php.

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

     <?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) відповідає імені файлу.

   • Запуск міграції: У папці з проектом виконайте для створення таблиці:

     vendor/bin/phalcon migration run

     Якщо виникають помилки, перевірте налаштування БД у app/config/config.php та чи активні сервіси MySQL/MariaDB у ServBay.

2. Налаштування підключення до БД (як показано раніше)

   Переконайтеся, що у секції 'database' файлу конфігурації вказано коректні значення під ServBay.

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:

   <?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-контейнер.

5. Тестування

   • Відкрийте https://servbay-phalcon-test.local/mysql-add — має з’явитись "User added successfully."
   • Відкрийте https://servbay-phalcon-test.local/mysql — побачите дані таблиці users у форматі JSON.

Приклад роботи з NoSQL: Redis

Покажемо інтеграцію Redis — для кешування даних у Phalcon через ServBay.

1. Встановлення розширення Redis

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

2. Налаштування підключення до Redis

   У app/config/config.php додайте секцію з параметрами Redis (за замовчуванням ServBay запускає Redis на 127.0.0.1:6379):

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

3. Додавання маршруту для демо-роботи з 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 та додайте екшен для демонстрації кешування через Redis:

   <?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-кешу (мають співпадати з config.php)
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // 1 година
               '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-контейнері для централізованого доступу.

5. Тестування

   Перейдіть до 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!", тобто дані повертаються з кешу.

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

• Q: При заході на сайт бачу 404 Not Found, що робити?
  • A: Переконайтесь, що у налаштуваннях ServBay для «кореневої папки сайту» вибрано саме public директорію проекту (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Перевірте, що Caddy чи Nginx запущено, а домен коректно розпізнається локально.
• Q: Помилка "Phalcon module not found" (Class 'Phalcon\Mvc\Application' not found)?
  • A: Це означає, що розширення Phalcon не активовано для обраної PHP-версії. Відкрийте ServBay, переконайтеся, що Phalcon ввімкнено для поточної PHP-версії та перезапустіть PHP. Дивіться інструкцію з активації Phalcon.
• Q: Проблеми з підключенням до БД?
  • A: Перевірте налаштування БД у app/config/config.php (хост, користувач, пароль, ім’я бази). Переконайтесь, що відповідний сервіс (MySQL/MariaDB) запущено у ServBay та створено базу даних.

Підсумок

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