Tworzenie i uruchamianie projektu Phalcon

Co to jest Phalcon?

Phalcon to otwartoźródłowy, wydajny framework PHP dla stron internetowych, zaimplementowany jako rozszerzenie napisane w C. Ta nietypowa konstrukcja pozwala Phalconowi osiągać wyjątkowo niskie zużycie zasobów oraz wysoką szybkość działania, znacząco wyprzedzając tradycyjne frameworki PHP. Phalcon bazuje na architekturze MVC (Model-View-Controller) i oferuje bogaty zestaw komponentów, takich jak ORM (mapowanie obiektowo-relacyjne), silnik szablonów, routing, cache, manager zdarzeń i wiele innych, ułatwiających szybkie budowanie dynamicznych i wydajnych aplikacji webowych oraz API.

Kluczowe cechy i zalety Phalcon

• Wyjątkowa wydajność: Phalcon jest uruchamiany jako rozszerzenie w C, przez co nie naraża na czasowe koszty związane z interpretacją i ładowaniem skryptów PHP.
• Oszczędność zasobów: Niska zajętość pamięci; doskonałe rozwiązanie dla projektów wymagających wysokiej wydajności i skalowalności.
• Kompletność funkcji: Większość kluczowych komponentów znajduje się w zestawie, redukując potrzebę korzystania z zewnętrznych bibliotek.
• Łatwość użycia: Przejrzyste API, konsystentna dokumentacja – również nowi użytkownicy szybko nauczą się frameworka.
• Wysoki poziom rozdzielenia: Modułowa budowa umożliwia swobodny wybór i wymianę komponentów zależnie od potrzeb projektu.
• Bezpieczeństwo: Wbudowane mechanizmy filtrujące wejście, pomoc w ochronie przed CSRF i innymi typowymi zagrożeniami.

Phalcon to doskonały wybór do budowy wydajnych, skalowalnych aplikacji webowych i API, zwłaszcza tam, gdzie liczy się szybkość i efektywność wykorzystania zasobów.

Tworzenie i uruchamianie projektu Phalcon w ServBay

ServBay to środowisko lokalne dla programistów, przeznaczone dla macOS, integrujące wiele wersji PHP, baz danych (MySQL, PostgreSQL, MongoDB, Redis), serwery WWW (Caddy, Nginx, Apache) i narzędzia developerskie. Dzięki ServBay łatwo skonfigurujesz i będziesz zarządzać środowiskiem dla projektu Phalcon.

Ten przewodnik krok po kroku pokaże, jak utworzyć podstawowy projekt Phalcon w ServBay, skonfigurować serwer WWW oraz zintegrować relacyjną bazę danych (MySQL) i NoSQL (Redis).

Wymagania wstępne

Przed rozpoczęciem upewnij się, że spełniasz następujące warunki:

1. ServBay jest zainstalowany i uruchomiony: Musisz mieć ServBay zainstalowany na macOS i uruchomiony.
2. Włączona odpowiednia wersja PHP: W ServBay sprawdź, czy wybrana wersja PHP jest aktywna.
3. Rozszerzenie Phalcon jest aktywne: ServBay posiada moduł Phalcon, który może być domyślnie wyłączony. Włącz rozszerzenie Phalcon odpowiednie dla Twojej wersji PHP wg wskazówek w dokumencie Jak włączyć wbudowany Phalcon w ServBay i zrestartuj usługę PHP.
4. Composer jest dostępny: Composer jest dostarczany domyślnie z ServBay (więcej), więc nie trzeba go instalować osobno. Sprawdź, czy możesz używać polecenia composer w terminalu.

Wersje Phalcon i DevTools

Phalcon i powiązany zestaw narzędzi developerskich (Phalcon DevTools) muszą być kompatybilne z wersją PHP. Poniższa tabela przedstawia zalecane dopasowanie wersji:

Wersja PHP	Zalecana wersja Phalcon	Zalecana wersja DevTools	Uwagi
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 (lub 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (oficjalny)	Wersja DevTools może mieć problemy z kompatybilnością z PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (poprawiony repozytorium)	Zalecane użycie poprawionej wersji społeczności dla lepszej kompatybilności.

Uwaga: Dla PHP 8.x i nowszych zaleca się użycie poprawionej wersji DevTools społeczności. W dalszej części przewodnika znajdziesz instrukcje jak zainstalować właściwy pakiet przez Composer.

Tworzenie projektu Phalcon

Zalecana ścieżka projektu

Dla lepszej organizacji ServBay zaleca umieszczanie projektów w domyślnym katalogu /Applications/ServBay/www. Ten przykład zakłada tworzenie projektu w tym miejscu.

1. Przejdź do katalogu www i utwórz folder projektu

   Uruchom terminal, przejdź do katalogu www ServBay i utwórz nowy katalog projektu (np. servbay-phalcon-app):

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

2. Instalacja Phalcon DevTools

   Phalcon DevTools to zbiór narzędzi CLI do generowania kodu, zarządzania migracjami itd. Instalujemy przez Composer – zależnie od wersji PHP komenda różni się:

   • Dla PHP 5.6, 7.0, 7.1 (DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • Dla PHP 7.2, 7.3, 7.4 (DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • Dla PHP 8.0, 8.1, 8.2, 8.3, 8.4 (DevTools dev-master – poprawiona wersja społeczności): W przypadku PHP 8.x użyj repozytorium poprawionej wersji społeczności – utwórz lub edytuj plik composer.json w katalogu projektu:

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

     Następnie uruchom:

     composer update

   Plik wykonywalny DevTools znajdziesz w vendor/bin/phalcon w nowo utworzonym katalogu vendor.

3. Tworzenie szkieletu projektu przez DevTools

   Użyj właśnie zainstalowanego DevTools do wygenerowania podstawowej struktury projektu. Domyślnie kod trafia do podkatalogu o nazwie projektu:

   vendor/bin/phalcon project servbay-phalcon-app

   To polecenie utworzy nowy podkatalog /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app z pełnym szkieletem projektu Phalcon.

4. Przejdź do katalogu kodu projektu

   Przejdź do katalogu z kodem projektu, gdzie będą wykonywane dalsze kroki:

   cd servbay-phalcon-app

   Aktualny katalog: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Konfiguracja projektu

Ustawienia projektu Phalcon zwykle są zebrane w pliku app/config/config.php. Tu skonfigurujesz połączenie do bazy danych, ścieżki i inne kluczowe parametry.

1. Edycja pliku konfiguracyjnego

   Otwórz plik /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php w dowolnym edytorze. Znajdź lub dodaj sekcję bazy danych. Domyślnym użytkownikiem MySQL w ServBay jest root bez hasła – ale dla bezpieczeństwa zaleca się ustawić silne hasło. W przykładzie użyto password jako placeholder, zmień według swojej konfiguracji. Przykładową nazwę bazy servbay_phalcon_app należy wcześniej utworzyć.

   return new \Phalcon\Config([
       // ... inne konfiguracje ...
       'database' => [
           'adapter' => 'Mysql', // lub 'Postgres'
           'host' => '127.0.0.1',
           'username' => 'root', // domyślny użytkownik ServBay
           'password' => 'password', // <-- wpisz swoje hasło
           'dbname' => 'servbay_phalcon_app', // <-- wpisz nazwę bazy
       ],
       // ... inne konfiguracje ...
   ]);

   Ważne: Upewnij się, że baza danych jest uruchomiona w ServBay (np. MySQL/MariaDB) oraz że użytkownik i hasło odpowiadają powyższym ustawieniom. Jeśli trzeba, utwórz bazę danych ręcznie – np. przez phpMyAdmin lub Adminer dostępne w ServBay.

Konfiguracja serwera WWW (funkcja „Strony” w ServBay)

Aby projekt był widoczny w przeglądarce, skonfiguruj w ServBay stronę internetową – wirtualny host wskazujący na katalog publiczny projektu.

1. Otwórz aplikację ServBay
2. Przejdź do ustawień „Strony”: Znajdź sekcję „Strony” na głównym ekranie.
3. Dodaj nową stronę:
   • Nazwa: np. My First Phalcon Dev Site.
   • Domena: np. servbay-phalcon-test.local. ServBay automatycznie przypisuje domeny .local do lokalnego środowiska.
   • Typ strony: wybierz PHP.
   • Wersja PHP: wybierz tę, którą masz z modułem Phalcon.
   • Katalog root: wskaż na katalog public swojego projektu: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Zapisz ustawienia: ServBay zastosuje zmiany, czasem wymaga restartu serwera WWW (Caddy/Nginx).

Więcej szczegółów w Dodawanie pierwszej strony. ServBay automatycznie skonfiguruje domenę oraz serwer WWW.

Przykładowy kod

Dodaj prosty kod, aby przetestować działanie projektu.

1. Konfiguracja routing

   Edytuj plik /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php, dodając prostą trasę obsługującą ścieżkę /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Definiuje domyślny routing. Ścieżka '/' trafia do IndexController i metody indexAction.
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Możesz dodać inne trasy ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Utwórz kontroler

   Edytuj (lub utwórz) plik /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php, dodając prostą metodę indexAction:

   <?php
   namespace App\Controllers; // Upewnij się, że namespace jest poprawny
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Obsługuje żądanie pod adresem '/'
       public function indexAction()
       {
           // Zwraca prosty tekst jako odpowiedź
           return 'Hello ServBay!';
       }
   }

Dostęp do strony

Po zapisaniu plików i uruchomieniu ServBay, otwórz przeglądarkę i przejdź do skonfigurowanej domeny:

https://servbay-phalcon-test.local

Jeżeli wszystko jest skonfigurowane poprawnie, ujrzysz komunikat Hello ServBay!.

Integracja z bazą danych

Phalcon udostępnia zaawansowaną warstwę ORM. ServBay pozwala na łatwą integrację z dowolną bazą, np. MySQL czy Redis. Poniżej przykłady.

Baza relacyjna: MySQL

Pokażemy, jak podłączyć się do MySQL w ServBay i wykonać przykładowe operacje.

1. Tworzenie schematu bazy danych (migracja)

   Phalcon DevTools obsługuje migracje – zarządzanie strukturą bazy.

   • Generowanie pliku migracji: W katalogu kodu uruchom:

     vendor/bin/phalcon migration generate

     Plik migracji pojawi się w katalogu migrations.

   • Edycja pliku migracji: W metodzie morph dodaj prostą strukturę tabeli users:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Klasa UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Nazwa klasy musi odpowiadać plikowi
     {
         /**
          * Wykonaj migrację
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Cofnij migrację
          *
          * @return void
          */
         public function down()
         {
             // Opcjonalnie: implementacja logiki rollbacku, np. usunięcie tabeli
             // $this->getConnection()->dropTable('users');
         }
     }

     Uwaga: Nazwa klasy UsersMigration_100 musi odpowiadać nazwie pliku migracji.

   • Uruchom migrację:

     vendor/bin/phalcon migration run

     Jeśli pojawi się błąd połączenia, sprawdź dane w app/config/config.php i czy baza MySQL/MariaDB działa w ServBay.

2. Konfiguracja połączenia do bazy (zrobione wcześniej)

   Sprawdź czy ustawienia 'database' w app/config/config.php odpowiadają Twojej bazie i użytkownikowi ServBay.

3. Dodaj trasę przykładową

   W pliku app/config/routes.php dodaj trasy dla insercji oraz zapytania:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Trasa do dodawania użytkownika
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Trasa do podglądu użytkowników
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Operacje bazy w kontrolerze

   W pliku app/controllers/IndexController.php dodaj metody do insercji i pobierania danych:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Adapter MySQL
   use Phalcon\Db\Enum; // Stałe dla fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Przykład dodawania użytkownika
       public function mysqlAddAction()
       {
           // Tworzenie połączenia (w praktyce lepiej użyć DI)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- wpisz swoje hasło
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Insert rekordu demo
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
   
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Przykład podglądu użytkowników
       public function mysqlAction()
       {
            $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password',
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Pobranie wszystkich użytkowników
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Wyświetlenie jako JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Uwaga: W produkcji zaleca się korzystanie z DI i Singletona dla połączenia, nie tworzenie go w każdej akcji.

5. Testowanie

   • Przejdź w przeglądarce pod https://servbay-phalcon-test.local/mysql-add – powinieneś zobaczyć "User added successfully.".
   • Potem odwiedź https://servbay-phalcon-test.local/mysql – zobaczysz JSON z danymi z tabeli users.

NoSQL: Redis

Pokażemy, jak użyć Redis jako cache w projekcie Phalcon na ServBay.

1. Instalacja rozszerzenia Redis

   ServBay domyślnie dostarcza rozszerzenie Redis dla PHP. Upewnij się, że jest włączone w wybranej wersji PHP (nie trzeba instalować przez pecl).

2. Konfiguracja połączenia z Redis

   W pliku app/config/config.php dodaj sekcję z ustawieniami połączenia:

   return new \Phalcon\Config([
       // ... inne konfiguracje ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // Podaj hasło jeśli zostało ustawione
       ],
       // ... inne konfiguracje ...
   ]);

3. Dodaj trasę przykładową

   W pliku app/config/routes.php dodaj trasę demonstracyjną dla cache Redis:

   <?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',
   ]);
   
   // Trasa demonstracyjna dla Redis cache
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Wykorzystanie Redis w kontrolerze

   W pliku app/controllers/IndexController.php dodaj metodę 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 adapter cache
   use Phalcon\Storage\SerializerFactory; // Fabryka serializatorów
   
   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);
       }
   
       // Przykład cache Redis
       public function redisAction()
       {
           // Utwórz instancję fabryki serializatorów
           $serializerFactory = new SerializerFactory();
   
           // Konfiguracja cache Redis (zgodna z 'cache' w config.php)
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'twoje_hasło'
           ];
   
           // Tworzenie instancji Redis cache
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Pobierz z cache
   
           if ($cachedData === null) {
               // Brak danych w cache
               echo "Dane nie znalezione w cache, pobieranie z źródła...";
               $cachedData = 'Dane pobrane z źródła: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Dane zapisane w cache.";
           } else {
               // Dane w cache dostępne
               echo "Dane znalezione w cache: ";
           }
   
           // Zwraca dane z cache (lub właśnie zapisane)
           return $cachedData;
       }
   }

   Uwaga: W dobrych praktykach cache powinno być serwisem w DI.

5. Testowanie

   Przejdź do https://servbay-phalcon-test.local/redis w przeglądarce:

   • Przy pierwszym wejściu zobaczysz "Dane nie znalezione w cache, pobieranie z źródła..." oraz "Dane zapisane w cache." i "Dane pobrane z źródła: Hello Redis from ServBay!".
   • Przy kolejnych wejściach w trakcie trwania cache zobaczysz "Dane znalezione w cache: " i "Dane pobrane z źródła: Hello Redis from ServBay!", co oznacza pobieranie z Redis.

FAQ

• Q: Co zrobić gdy pojawia się błąd 404 Not Found?
  • A: Sprawdź, czy katalog root w ustawieniach strony ServBay wskazuje na katalog public projektu (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Sprawdź też czy serwer WWW działa poprawnie i domena lokalna jest obsługiwana.
• Q: „Nie znaleziono modułu Phalcon” (np. Class 'Phalcon\Mvc\Application' not found)?
  • A: Oznacza to, że rozszerzenie Phalcon nie jest aktywne. Aktywuj rozszerzenie dla wybranej wersji PHP w ServBay i zrestartuj usługę PHP. Zobacz poradnik Jak włączyć wbudowany Phalcon w ServBay.
• Q: Brak połączenia z bazą danych?
  • A: Sprawdź dane w pliku app/config/config.php (host, użytkownik, hasło, nazwa bazy). Upewnij się, że usługa MySQL/MariaDB jest uruchomiona, użytkownik ma odpowiednie uprawnienia i baza istnieje.

Podsumowanie

ServBay pozwala na szybkie uruchomienie wydajnego, lokalnego środowiska dla frameworka Phalcon. Ten przewodnik pokazał, jak stworzyć projekt, skonfigurować serwer WWW oraz zintegrować z MySQL i Redis. Dzięki gotowym pakietom oraz intuicyjnemu interfejsowi ServBay znacznie upraszcza konfigurację, umożliwiając skupienie się na programowaniu aplikacji Phalcon. Mamy nadzieję, że ten poradnik ułatwi Ci rozpoczęcie efektywnej pracy w ServBay i Phalcon!