Creating and Running a Phalcon Project

What Is Phalcon?

Phalcon is an open-source, high-performance PHP web framework implemented as a C extension. This unique approach gives Phalcon exceptionally low resource usage and extraordinary execution speed, significantly outperforming most traditional PHP frameworks. Phalcon follows the MVC (Model-View-Controller) architecture and offers developers a wide array of powerful components, including ORM, template engine, routing, caching, and an event manager, enabling rapid development of robust, high-speed web applications and APIs.

Key Features and Advantages of Phalcon

• Exceptional Performance: As a C extension, Phalcon sidesteps the overhead of PHP script parsing and loading, delivering native-level performance.
• Resource Efficiency: Extremely low memory footprint, ideal for applications with demanding scalability and performance requirements.
• Comprehensive Functionality: Built-in core components for web development reduce reliance on third-party libraries.
• Ease of Use: Clear and consistent APIs, along with thorough documentation, make Phalcon accessible even for newcomers.
• Highly Decoupled: Components are designed independently, allowing developers to use or swap out parts as needed.
• Security: Offers a suite of security features, including input filtering and CSRF protection.

Phalcon is an excellent choice for building high-performance, scalable web applications and APIs, especially when speed and resource efficiency are critical.

Creating and Running a Phalcon Project Using ServBay

ServBay is a local web development environment specially designed for macOS. It comes bundled with multiple versions of PHP, databases (such as MySQL, PostgreSQL, MongoDB, Redis), web servers (Caddy, Nginx, Apache), and other developer tools. With ServBay, you can easily set up and manage the ideal runtime for your Phalcon projects.

This guide walks you through creating a basic Phalcon project using ServBay’s PHP environment, configuring the web server for access, and integrating both relational (MySQL) and NoSQL (Redis) databases.

Prerequisites

Before getting started, make sure you meet the following requirements:

1. ServBay is installed and running: Ensure ServBay is successfully installed and launched on your macOS system.
2. Required PHP version enabled: In ServBay, make sure the PHP version you intend to use is enabled.
3. Phalcon module enabled: ServBay includes the Phalcon module, but it may not be enabled by default. Follow the instructions in How to Enable ServBay’s Built-in Phalcon Module to enable the Phalcon extension for your chosen PHP version and restart the PHP service.
4. Composer available: ServBay comes with Composer pre-installed, so you don’t need to install it yourself. Make sure you can use the composer command directly in the terminal.

Phalcon Versions and DevTools Compatibility

The Phalcon framework and its official development tools (Phalcon DevTools) must be compatible with your PHP version. The table below shows commonly used PHP versions and recommended corresponding Phalcon framework and DevTools versions:

PHP Version	Recommended Phalcon Version	Recommended Phalcon DevTools Version	Notes
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 (or 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (official)	Official DevTools may have compatibility issues on PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (use fixed community repo)	It’s recommended to use a community-maintained fixed version.

Important: For PHP 8.x and above, the official Phalcon DevTools may not be fully compatible. It’s recommended to use the fixed version maintained by the community. The following project creation steps include instructions on how to install the fixed DevTools via Composer.

Creating a Phalcon Project

Recommended project directory

For easier management, ServBay suggests placing all web projects in the default site root directory: /Applications/ServBay/www. This example will use this directory to create the project.

1. Navigate to the site root and create a project folder

   Open your terminal, go to ServBay’s site root, and create a new folder for your Phalcon project (for example, servbay-phalcon-app):

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

2. Install Phalcon DevTools

   Phalcon DevTools is a CLI toolkit for rapid code generation, project scaffolding, and database migrations. It’s installed via Composer. Installation varies a bit depending on your PHP version:

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • For PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools dev-master, fixed version): As the official DevTools may not fully support PHP 8.x, use Composer to install the community-maintained fixed version. In your project root (/Applications/ServBay/www/servbay-phalcon-app), create or edit composer.json with the following configuration:

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

     Then, run Composer update to install DevTools:

     composer update

   Composer will create a vendor directory in your project root (servbay-phalcon-app) with the DevTools executable at vendor/bin/phalcon.

3. Create the project skeleton with DevTools

   Now, use the DevTools CLI to generate the basic structure. By default, project code is placed in a subdirectory (named the same as your project):

   vendor/bin/phalcon project servbay-phalcon-app

   This will create a new subdirectory: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app, containing a fully scaffolded Phalcon project.

4. Navigate to the project code directory

   Change to your new code directory for further setup:

   cd servbay-phalcon-app

   You should now be in /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configuring the Project Environment

Phalcon project configuration is typically handled in the app/config/config.php file, including database connection info and app paths.

1. Edit the config file

   Open /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php in your favorite editor. Find or add the database configuration block. ServBay’s MariaDB/MySQL default user is root with no password, but for security, you should set a strong password. Here, password is a placeholder—change it to your real credentials. The database name servbay_phalcon_app is used for this example (make sure to create it).

   return new \Phalcon\Config([
       // ... other config ...
       'database' => [
           'adapter' => 'Mysql', // Or 'Postgres', etc.
           'host' => '127.0.0.1',
           'username' => 'root', // ServBay default
           'password' => 'password', // <-- Change to your actual database password
           'dbname' => 'servbay_phalcon_app', // <-- Change to your actual database name
       ],
       // ... other config ...
   ]);

   Important: Make sure the relevant database service (MySQL or MariaDB) is running in ServBay and credentials match this configuration. You need to manually create the servbay_phalcon_app database, which you can do using ServBay’s database management tools (phpMyAdmin or Adminer).

Setting Up the Web Server (Via ServBay Websites)

To access your Phalcon project in the browser, use ServBay’s Websites feature to configure a virtual host pointing to your project's web-accessible directory.

1. Open the ServBay application
2. Go to the "Websites" settings: On ServBay’s main interface, click on the "Websites" section.
3. Add a new website:
   • Name: Enter something descriptive, e.g., My First Phalcon Dev Site.
   • Domain: Specify the domain you want to use in the browser, e.g., servbay-phalcon-test.local. ServBay automatically maps .local domains to your computer.
   • Website type: Select PHP.
   • PHP Version: Choose the version with the enabled Phalcon module.
   • Site root directory: Crucial step—Phalcon’s entry file (index.php) is in the public folder, so set your root to: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Save settings: Save your new site config. ServBay applies the changes automatically; you may need to restart your web server (Caddy or Nginx).

For step-by-step instructions, see Adding Your First Website. ServBay handles domain resolution and web server configuration behind the scenes.

Adding Example Code

Let’s add some simple code to verify your project setup is working.

1. Configure routing

   Edit /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php to add a basic route for the root path /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Define default route: map '/' to IndexController's indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Add more route rules as needed ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Create a controller

   Edit /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php (create it if it doesn’t exist) with a simple indexAction method:

   <?php
   namespace App\Controllers; // Ensure correct namespace
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Handle requests to '/'
       public function indexAction()
       {
           // Return a simple string as a response
           return 'Hello ServBay!';
       }
   }

Accessing Your Website

Once you’ve saved all files and confirmed ServBay is running, open your browser and visit the domain you set up in ServBay:

https://servbay-phalcon-test.local

If everything is configured correctly, you should see the output Hello ServBay!.

Integrating Databases

Phalcon provides a powerful database abstraction layer and ORM. ServBay integrates various databases, allowing for easy connection with your Phalcon project. The examples below use MySQL and Redis.

Relational Database Example: MySQL

Here’s how to connect Phalcon to ServBay’s MySQL and perform simple insert and query operations.

1. Creating the Database Structure (with Migrations)

   Phalcon DevTools supports database migrations, a standard method for schema versioning.

   • Generate migration file: Run the DevTools command in your project directory to generate a blank migration:

     vendor/bin/phalcon migration generate

     This creates a new migration in the migrations folder, named like YYYYMMDDHHMMSS_MigrationName.php.

   • Edit the migration file: Open the new migration and edit its morph method to define a simple users table:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Class name must match filename
     {
         /**
          * 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()
         {
             // Optional: implement rollback logic, e.g., drop the table
             // $this->getConnection()->dropTable('users');
         }
     }

     Note: The class name (e.g., UsersMigration_100) must match the migration file’s class and filename.

   • Run the migration: In the project directory, execute DevTools to apply the migration and create the users table:

     vendor/bin/phalcon migration run

     If you encounter connection errors, double-check your database settings in app/config/config.php and ensure MySQL/MariaDB is running in ServBay.

2. Setup database connection (already done above)

   Confirm the 'database' block in app/config/config.php points to the correct ServBay MySQL/MariaDB instance (usually host 127.0.0.1, port 3306, user root, and your chosen password).

3. Add example routes

   Edit app/config/routes.php to add routes for inserting and selecting user data:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Route to insert user data
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Route to query user data
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implement database operations in the controller

   Edit app/controllers/IndexController.php, adding mysqlAddAction and mysqlAction for DB operations. Here we use Phalcon’s database adapter directly.

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // MySQL adapter
   use Phalcon\Db\Enum; // For fetchAll mode constants
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Insert user example
       public function mysqlAddAction()
       {
           // Get a DB connection directly (normally set up as a service)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Change to your DB password
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Insert a demo user record
           $success = $connection->insert(
               'users', // Table name
               ['ServBay Demo User', 'demo@servbay.test'], // Values
               ['name', 'email'] // Columns
           );
   
           // Output result
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Query and display user data
       public function mysqlAction()
       {
            // Get DB connection
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Change to your DB password
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Query all users
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Output as JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Note: In production, set up DB connection in the service container and use dependency injection, rather than creating connections in each action.

5. Testing the example

   • Visit https://servbay-phalcon-test.local/mysql-add in your browser. On success, you’ll see "User added successfully."
   • Visit https://servbay-phalcon-test.local/mysql. You should see JSON output of your users table, including the demo record.

NoSQL Database Example: Redis

Here's how to use ServBay's Redis service as a cache in your Phalcon project.

1. Install Redis extension

   ServBay’s PHP packages generally include popular extensions like Redis. You don’t need to install manually—just enable the Redis extension for your chosen PHP version.

2. Configure Redis connection

   In app/config/config.php, add Redis connection info. ServBay Redis runs at 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... other config ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Redis DB index (default 0)
           'persistent' => false, // Persistent connection
           'auth' => null, // Add your password if Redis is gated
       ],
       // ... other config ...
   ]);

3. Add example route

   Edit app/config/routes.php to add a new route for Redis cache 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',
   ]);
   
   // Route for Redis cache demo
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Use Redis cache in the controller

   Edit app/controllers/IndexController.php to add a redisAction showing Redis cache usage:

   <?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 demo
       public function redisAction()
       {
           // Create a serializer factory instance
           $serializerFactory = new SerializerFactory();
   
           // Configure Redis cache options
           // Note: Keep this in sync with the 'cache' section in app/config/config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // Cache time in seconds (e.g., 1 hour)
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'your_redis_password', // Add if needed
           ];
   
           // Create Redis cache adapter instance
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Try getting cached data
   
           if ($cachedData === null) {
               // No data in cache
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData); // Write to cache
               echo "Data stored in cache.";
           } else {
               // Data found in cache
               echo "Data found in cache: ";
           }
   
           // Return cached data (or just written)
           return $cachedData;
       }
   }

   Note: In production, configure caching in the service container for easier app-wide access.

5. Test the example

   Visit https://servbay-phalcon-test.local/redis in your browser.

   • On first visit, you’ll see "Data not found in cache, fetching from source...Data stored in cache." and "Data fetched from source: Hello Redis from ServBay!"
   • On subsequent visits (within cache lifetime), you’ll see "Data found in cache:" and "Data fetched from source: Hello Redis from ServBay!", confirming data is retrieved from Redis.

Frequently Asked Questions (FAQ)

• Q: What if I get a 404 Not Found error accessing the site?
  • A: Confirm your ServBay website settings point the "Site root directory" to your Phalcon project’s public folder (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Also, check that ServBay’s web server (Caddy or Nginx) is running and local domain resolution works.
• Q: Get an error about missing Phalcon module (e.g., Class 'Phalcon\Mvc\Application' not found)?
  • A: Usually, the Phalcon extension isn’t enabled in your PHP version. Go back to the ServBay UI, enable the Phalcon extension for your selected PHP version, and restart PHP. See How to Enable ServBay’s Built-in Phalcon Module.
• Q: Database connection failed?
  • A: Double-check the database settings (host, username, password, database name) in app/config/config.php, ensure the relevant DB service is running in ServBay, and the user has access to the database, which must exist.

Conclusion

ServBay lets you quickly set up a high-performance local environment for the Phalcon framework. This guide covers building your project skeleton, configuring your web server, and integrating MySQL and Redis databases. With ServBay’s bundled software and simple management interface, local environment setup and maintenance are streamlined, so you can focus on developing your Phalcon application. We hope this guide helps you get started with fast, efficient web development using ServBay and Phalcon!