Een Phalcon-project maken en uitvoeren

Wat is Phalcon?

Phalcon is een open-source, high-performance PHP webframework dat als een C-extensie is geïmplementeerd. Door deze unieke aanpak verbruikt Phalcon uitzonderlijk weinig systeembronnen en biedt het ongeëvenaarde snelheid, waardoor het beter presteert dan de meeste traditionele PHP frameworks. Phalcon volgt het MVC-model (Model-View-Controller) en voorziet ontwikkelaars van een scala aan krachtige componenten, waaronder ORM, template-engines, routing, caching en event managers. Hierdoor kun je snel krachtige en efficiënte webapplicaties en API’s ontwikkelen.

Belangrijkste kenmerken en voordelen van Phalcon

• Uitstekende prestaties: Als C-extensie vermijdt Phalcon de overhead van PHP-script parsing en biedt native-level snelheid.
• Efficiënt gebruik van resources: Zeer laag geheugengebruik, geschikt voor applicaties waarbij performance en schaalbaarheid belangrijk zijn.
• Volledig uitgerust: Bevat de meeste essentiële onderdelen voor webontwikkeling, waardoor de afhankelijkheid van externe bibliotheken afneemt.
• Gebruiksvriendelijk: Duidelijke, consistente API en uitgebreide documentatie; ook beginners kunnen snel aan de slag.
• Hoge modulariteit: Componenten zijn los gekoppeld, zodat je kunt kiezen welke je gebruikt of vervangt.
• Veiligheid: Voorzien van uitgebreide veiligheidscomponenten zoals input filtering en CSRF-bescherming.

Phalcon is ideaal voor het bouwen van snelle, schaalbare webapplicaties en API’s, zeker wanneer prestaties en resource-optimalisatie cruciaal zijn.

Een Phalcon-project starten met ServBay

ServBay is een lokale webontwikkelomgeving speciaal voor macOS, met geïntegreerde ondersteuning voor verschillende PHP-versies, databases (zoals MySQL, PostgreSQL, MongoDB, Redis) en webservers (Caddy, Nginx, Apache) plus andere ontwikkeltools. Met ServBay kun je eenvoudig de benodigde omgeving voor je Phalcon-project opzetten en beheren.

Deze handleiding begeleidt je bij het gebruik van ServBay’s PHP-omgeving om een basis Phalcon-project aan te maken, een webserver te configureren voor toegang tot het project, en zowel een relationele database (MySQL) als een NoSQL database (Redis) te integreren.

Vereisten

Controleer voor je begint het volgende:

1. ServBay geïnstalleerd en actief: Zorg dat ServBay geïnstalleerd is op je macOS en draait.
2. Benodigde PHP-versie ingeschakeld: Zet binnen ServBay de juiste PHP-versie aan die je wilt gebruiken.
3. Phalcon-module ingeschakeld: ServBay wordt geleverd met de Phalcon-module, maar deze is standaard mogelijk uitgeschakeld. Volg de instructies uit de Phalcon-module inschakelen in ServBay documentatie om de Phalcon-extensie voor de juiste PHP-versie te activeren en herstart vervolgens de PHP-service.
4. Composer beschikbaar: Composer wordt standaard meegeleverd met ServBay (Composer in ServBay), je hoeft dus niets apart te installeren. Controleer of het composer commando werkt in de terminal.

Verschillende versies van Phalcon en DevTools

Het is belangrijk dat je de versie van het Phalcon-framework en de bijbehorende DevTools afstemt op de PHP-versie die je gebruikt. Zie de tabel hieronder voor veel voorkomende combinaties:

PHP-versie	Aanbevolen Phalcon-versie	Aanbevolen Phalcon DevTools versie	Opmerkingen
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 (of 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (officieel)	Officiële DevTools kunnen compatibiliteitproblemen hebben op PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (gebruik gefixte repo)	Gebruik een community-versie voor betere compatibiliteit.

Opmerking: Voor PHP 8.x en nieuwer kan de officiële Phalcon DevTools minder compatibel zijn. Het is aan te raden een gefixte community-versie te kiezen. In de volgende stappen lees je hoe je deze via Composer gebruikt.

Phalcon-project aanmaken

Aanbevolen opslaglocatie voor websites

Om projecten eenvoudig te beheren, raadt ServBay aan al je websites te plaatsen in de standaard webroot: /Applications/ServBay/www. In dit voorbeeld maken we daar ons project aan.

1. Ga naar de webroot en maak een projectmap aan

   Open een terminal, ga naar ServBay’s webroot en maak een map voor je Phalcon-project, bijvoorbeeld servbay-phalcon-app:

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

2. Installeer Phalcon DevTools

   Phalcon DevTools is een set commandline-hulpprogramma’s voor snelle codegeneratie, het aanmaken van een project-skelet, database-migraties en meer. Installeer ze via Composer, afhankelijk van de PHP-versie:

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • Voor PHP 8.0–8.4 (Phalcon DevTools dev-master – gefixte versie): Omdat de officiële DevTools niet altijd werken met PHP 8.x, voeg je in je composer.json in de projectroot (/Applications/ServBay/www/servbay-phalcon-app) het volgende toe:

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

     Installeer DevTools vervolgens met:

     composer update

   Composer creëert in de projectroot een vendor map, met het DevTools uitvoerbare bestand onder vendor/bin/phalcon.

3. Een project-skelet genereren met DevTools

   Gebruik nu het DevTools commando om de basisprojectstructuur te maken. Het project komt in een submap (standaard dezelfde naam als je project, hier servbay-phalcon-app):

   vendor/bin/phalcon project servbay-phalcon-app

   Dit genereert onder /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app het volledige Phalcon-project.

4. Ga naar de map met de projectcode

   Ga in de terminal naar de submap met je projectcode:

   cd servbay-phalcon-app

   Je bevindt je nu in /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Projectconfiguratie

De configuratie van een Phalcon-project gebeurt doorgaans in app/config/config.php, waar je o.a. databaseverbindingen en padinstellingen set.

1. Bewerk het configuratiebestand

   Open /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php in je favoriete editor. Zorg dat de databaseconfiguratie aanwezig is. ServBay’s MySQL/MariaDB gebruikersnaam is standaard root en het wachtwoord leeg; voor veiligheid raadt ServBay aan een sterk wachtwoord in te stellen (hier als voorbeeld password, vervang dit naar wens). De database servbay_phalcon_app moet je zelf aanmaken.

   return new \Phalcon\Config([
       // ... Overige configuratie ...
       'database' => [
           'adapter' => 'Mysql', // of 'Postgres'
           'host' => '127.0.0.1',
           'username' => 'root', // ServBay standaard root
           'password' => 'password', // <-- Vervang door jouw wachtwoord
           'dbname' => 'servbay_phalcon_app', // <-- Vervang door jouw databasenaam
       ],
       // ... Overige configuratie ...
   ]);

   Belangrijk: Activeer de database service (MySQL of MariaDB) in ServBay. Controleer dat gebruikersnaam en wachtwoord kloppen en de database (servbay_phalcon_app) bestaat. Je kunt deze beheren via ServBay’s phpMyAdmin of Adminer.

Webserver instellen (via ServBay Websites)

Om je Phalcon-project via de browser te openen, configureer je een virtuele host in ServBay en wijs je die toe aan je publieke map.

1. Open ServBay
2. Ga naar 'Websites': Klik op het tabblad 'Websites' in de hoofdinterface.
3. Voeg een nieuwe site toe:
   • Naam: Een herkenbare naam, bijvoorbeeld My First Phalcon Dev Site.
   • Domeinnaam: Geef de gewenste URL, bijvoorbeeld servbay-phalcon-test.local. ServBay koppelt .local automatisch aan je lokale machine.
   • Webtype: Kies PHP.
   • PHP-versie: Selecteer de PHP-versie waarmee je Phalcon hebt ingeschakeld.
   • Webroot: Phalcon’s entrypoint (index.php) staat in de public map: voeg toe als root /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Bewaar: Sla de configuratie op. ServBay past alles toe en je moet mogelijk de webserver (Caddy/Nginx) herstarten.

Zie Eerste website toevoegen voor meer uitleg. ServBay regelt lokale DNS en serverconfiguratie automatisch.

Voorbeeldcode toevoegen

We voegen nu eenvoudige code toe om te testen of het project werkt.

1. Routing instellen

   Bewerk /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php en voeg een basisroute toe voor het root-pad /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Standaardroute: map root ('/') naar IndexController’s index-actie
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Meer routes kunnen hier toegevoegd worden ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Controller aanmaken

   Bewerk /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php (maak aan indien nodig):

   <?php
   namespace App\Controllers; // Zorg dat de namespace juist is
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Verwerkt requests naar '/'
       public function indexAction()
       {
           // Stuurt een simpele string terug als response
           return 'Hello ServBay!';
       }
   }

Website bezoeken

Sla alles op en controleer dat ServBay draait. Ga in je browser naar:

https://servbay-phalcon-test.local

Als alles goed is ingesteld zie je "Hello ServBay!" in je browser.

Database-integratie

Phalcon heeft krachtige database-abstractie en ORM-functionaliteit. ServBay integreert eenvoudig met diverse databases – hieronder voorbeelden met MySQL en Redis.

Relationele database voorbeeld: MySQL

Hier laten we zien hoe je via Phalcon’s database-adapter verbindt met MySQL, en eenvoudig data toevoegt en opvraagt.

1. Maak de database structuur aan (met migraties)

   DevTools ondersteunt migraties - handig voor databaseversiebeheer.

   • Genereer een migratiebestand: In de codefolder (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app):

     vendor/bin/phalcon migration generate

     Er wordt een leeg migratiebestand gemaakt in de map migrations, bijvoorbeeld YYYYMMDDHHMMSS_MigrationName.php.

   • Bewerk migratiebestand: Open het nieuwe bestand en beschrijf een simpele users tabel in de morph-methode:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Zorg dat de classnaam overeenkomt met bestandsnaam
     {
         /**
          * Voer de migraties uit
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Draait de migratie terug
          *
          * @return void
          */
         public function down()
         {
             // Optioneel: rollback, bijvoorbeeld verwijderen van de tabel
             // $this->getConnection()->dropTable('users');
         }
     }

     Let op: De classnaam (UsersMigration_100) moet matchen met de bestandsnaam (die meestal tijdstip en naam bevat).

   • Voer migratie uit: In de codefolder je migratie uitvoeren; daarmee wordt de users tabel aangemaakt:

     vendor/bin/phalcon migration run

     Bij fouten: check je databaseconfig in app/config/config.php en of de MySQL/MariaDB service draait in ServBay.

2. Databaseverbinding instellen (zie eerdere stap)

   Controleer dat 'database' in app/config/config.php wijst naar ServBay’s MySQL/MariaDB (standaard host 127.0.0.1, poort 3306, user root, wachtwoord zoals ingesteld).

3. Voorbeeldroutes toevoegen

   Bewerk app/config/routes.php en voeg routes toe voor data toevoegen en opvragen:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Route om gebruiker toe te voegen
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Route om alle gebruikers te tonen
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Database-operaties in de controller

   Bewerk app/controllers/IndexController.php en voeg methodes toe voor add/query via MySQL. Hier direct de Phalcon database-adapter gebruikt.

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Import MySQL Adapter
   use Phalcon\Db\Enum; // Voor fetchAll mode constants
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Voorbeeld: Gebruiker toevoegen
       public function mysqlAddAction()
       {
           // Maak een databaseverbinding (bij voorkeur via DI container)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Vervang door jouw wachtwoord
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Voeg de gebruiker toe
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
   
           // Toon resultaat
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Voorbeeld: Gebruikers opvragen
       public function mysqlAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Vervang door jouw wachtwoord
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Haal alle gebruikers op
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Resultaat als JSON tonen
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Let op: In productie-projecten registreer je databaseverbinding bij voorkeur als service in de DI container, en injecteer je hem in de controller via dependency injection.

5. Voorbeeld bezoeken

   • Ga in de browser naar https://servbay-phalcon-test.local/mysql-add; "User added successfully." verschijnt bij succes.
   • Open daarna https://servbay-phalcon-test.local/mysql; je ziet nu de gebruikers in JSON-formaat, waaronder je net toegevoegde demo-gebruiker.

NoSQL-database voorbeeld: Redis

Hier zie je hoe je ServBay’s Redis-service als cache in een Phalcon-project gebruikt.

1. Redis-extensie installeren

   PHP-extensie voor Redis wordt standaard meegeleverd in ServBay. Je hoeft alleen Redis in te schakelen voor de juiste PHP-versie.

2. Redis-verbinding configureren

   Voeg in app/config/config.php de Redis-instellingen toe. ServBay’s Redis draait standaard op 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... Overige configuratie ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Redis DB index, standaard 0
           'persistent' => false, // Gebruik persistent verbinding?
           'auth' => null, // Vul wachtwoord in als Redis beveiligd is
       ],
       // ... Overige configuratie ...
   ]);

3. Voorbeeldroute toevoegen

   Bewerk app/config/routes.php en voeg een route toe voor Redis-demo:

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

4. Redis cache gebruiken in de controller

   Voeg in app/controllers/IndexController.php een nieuwe methode toe:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Redis cache adapter
   use Phalcon\Storage\SerializerFactory; // Serializer factory
   
   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-cache voorbeeld
       public function redisAction()
       {
           // Maak een serializer factory
           $serializerFactory = new SerializerFactory();
   
           // Cache opties (gelijk aan config.php)
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // seconden
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'je_redis_wachtwoord', // indien van toepassing
           ];
   
           // Maak Redis cache
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // Niet in cache
               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 {
               // Wel in cache
               echo "Data found in cache: ";
           }
   
           // Retourneer cached data
           return $cachedData;
       }
   }

   Let op: In grotere projecten registreer je cache adapters bij voorkeur als services in de DI-container.

5. Voorbeeld bezoeken

   Open je browser op https://servbay-phalcon-test.local/redis.

   • Bij eerste bezoek zie je: "Data not found in cache, fetching from source...Data stored in cache." én "Data fetched from source: Hello Redis from ServBay!".
   • Bij volgende bezoek (binnen 1 uur): "Data found in cache: " en "Data fetched from source: Hello Redis from ServBay!" – het komt dan uit Redis.

Veelgestelde vragen (FAQ)

• Vraag: Ik krijg een 404 Not Found bij bezoek van mijn site, wat nu?
  • Antwoord: Controleer of de ServBay website-root juist ingesteld staat op de public map van je Phalcon-project (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Kijk of de webserver (Caddy/Nginx) en lokale domein-setup goed werken.
• Vraag: Foutmelding: Phalcon module niet gevonden (Class 'Phalcon\Mvc\Application' not found)?
  • Antwoord: Waarschijnlijk is de Phalcon-extensie niet ingeschakeld bij je PHP-versie. Activeer Phalcon in ServBay en herstart PHP, zie Phalcon inschakelen in ServBay.
• Vraag: Databaseverbinding werkt niet?
  • Antwoord: Controleer de instellingen in app/config/config.php – host, gebruikersnaam, wachtwoord en database. Zorg dat de MySQL/MariaDB service in ServBay draait en dat de gebruiker toegang heeft en de database bestaat.

Samenvatting

Met ServBay kun je snel en eenvoudig een krachtige ontwikkelomgeving opzetten voor het Phalcon-framework. Deze handleiding laat zien hoe je een project-skelet maakt, de webserver configureert en zowel MySQL als Redis integreert. Dankzij de geïntegreerde tools en gebruiksvriendelijke interface van ServBay kun je je focussen op de ontwikkeling van je Phalcon-applicaties, zonder je zorgen te maken over de installatie en configuratie van je lokale omgeving. Hopelijk helpt deze gids je vlot op weg met ServBay en Phalcon voor efficiënte webontwikkeling!