Phalcon is a high-performance PHP framework delivered as a C extension, making it dramatically faster than many traditional PHP frameworks. Installing it on Ubuntu requires a slightly different process compared to typical PHP frameworks because you must compile or install an extension rather than just extract files. This comprehensive guide will walk you through everything you need to know—from understanding what Phalcon is, to preparing your system, installing dependencies, compiling it from source, enabling it in PHP, verifying the installation, and handling common issues.
Whether you are a beginner, intermediate user, or an experienced system administrator, this 3000-word article serves as a complete, practical reference to help you install and configure Phalcon successfully on Ubuntu.
1. Introduction to Phalcon
Phalcon is an open-source, full-stack PHP framework known for its incredibly fast performance. Unlike typical PHP frameworks such as Laravel, CodeIgniter, or Symfony, Phalcon is implemented as a compiled C extension, which means the framework’s code runs at the speed of compiled language rather than being parsed on every request like standard PHP frameworks.
1.1 Why Phalcon is Unique
Phalcon is designed for:
- High performance: It delivers minimal overhead and extremely fast execution.
- Efficient resource usage: Lower CPU usage and memory consumption.
- Low-level architecture: Built as a PHP extension, loaded directly into memory.
- Rich ecosystem: Includes ORM, MVC architecture, security tools, caching, and more.
1.2 Phalcon Versions on Ubuntu
Phalcon supports different PHP versions, and installation steps may vary slightly. This guide focuses on general installation steps that work for most Ubuntu versions (20.04, 22.04, etc.) and PHP versions (7.4, 8.0, 8.1, 8.2).
2. Before You Begin: Understanding Ubuntu & PHP Integration
Phalcon is installed as a dynamic extension and loaded through php.ini or PHP’s mods-available directory. Unlike typical frameworks that live in your project directory, the Phalcon extension is stored in your PHP extensions folder (/usr/lib/php/<version>/).
2.1 Requirements Checklist
Before installing Phalcon, make sure you have:
- A supported Ubuntu version (20.04 or newer recommended)
- PHP installed (CLI + FPM or Apache module)
- Development tools like
gcc,make, and build-essential - Required PHP development packages
- Git installed to clone the source code
- Permissions to install system packages
3. Step 1: Updating Your Ubuntu System
Start by updating your server. This ensures that all packages are up to date and compatible.
sudo apt update && sudo apt upgrade -y
This simple step prevents compatibility issues during the build process.
4. Step 2: Installing Required PHP Packages
Since Phalcon is a PHP extension, you need to install PHP and certain development packages. These packages allow you to build extensions from source.
4.1 Install PHP and Core Modules
sudo apt install php php-dev php-xml php-mbstring php-mysql php-fpm php-cli -y
4.2 Install Developer Tools
Phalcon cannot be compiled without compiling tools:
sudo apt install git gcc make re2c autoconf -y
4.3 Install Additional Libraries
Some components may require additional libraries:
sudo apt install libpcre3-dev libtool -y
4.4 Verifying PHP Version
Run:
php -v
This will confirm your PHP version and ensure the development packages match.
5. Step 3: Cloning the Phalcon Repository
Phalcon’s source is available on GitHub.
5.1 Clone the C-Extension Repository
git clone https://github.com/phalcon/cphalcon.git
This downloads the Phalcon extension source code.
5.2 Navigate to the Build Directory
cd cphalcon/build
You are now inside the directory that contains the build script for Phalcon.
6. Step 4: Building Phalcon From Source
This is the core step where you compile the extension.
6.1 Run the Build Script
Phalcon provides a build script to simplify the compilation process:
sudo ./install
6.2 What Happens During Installation
The build script:
- Generates necessary C files
- Compiles the extension into a
.sofile - Installs it into your PHP extensions folder
The compiled file typically ends up here:
/usr/lib/php/<php-version>/phalcon.so
7. Step 5: Enabling Phalcon in PHP
7.1 Create the phalcon.ini File
echo "extension=phalcon.so" | sudo tee /etc/php/*/mods-available/phalcon.ini
7.2 Enable the Extension
sudo phpenmod phalcon
7.3 Restart PHP-FPM or Apache
If using PHP-FPM:
sudo systemctl restart php*-fpm
If using Apache:
sudo systemctl restart apache2
8. Step 6: Verifying Phalcon Installation
To confirm Phalcon is installed:
php -m | grep phalcon
You should see:
phalcon
You can also run:
php --ri phalcon
This prints the Phalcon version and configuration details.
9. Installing Phalcon DevTools (Optional But Recommended)
Phalcon DevTools provide CLI commands for generating models, controllers, modules, and project scaffolding.
9.1 Clone the DevTools Repository
git clone https://github.com/phalcon/phalcon-devtools.git
9.2 Move It to /opt
sudo mv phalcon-devtools /opt/
9.3 Make It Executable
sudo ln -s /opt/phalcon-devtools/phalcon.php /usr/bin/phalcon
sudo chmod +x /usr/bin/phalcon
9.4 Test DevTools
phalcon
You should see CLI commands available.
10. Creating a New Phalcon Project
Once installation is complete, you can create a new project:
phalcon create-project myproject
This creates a default MVC project structure.
11. Troubleshooting Common Issues
Installing Phalcon involves compilation, so errors may occur. Here are solutions for common issues.
11.1 PHP Extension Directory Error
If install script cannot locate PHP extension directory:
php-config --extension-dir
Ensure the build script uses this directory or manually copy the extension:
sudo cp modules/phalcon.so /usr/lib/php/<version>/
11.2 Missing Development Tools
If you see errors like:
make: command not found
gcc: command not found
Install them:
sudo apt install build-essential -y
11.3 Unsupported PHP Version
Phalcon may not support every PHP release immediately. Check compatibility:
- PHP 7.x → Phalcon 4 or 5
- PHP 8.x → Phalcon 5+
11.4 Apache Not Loading Phalcon
Make sure both CLI and Apache are using the same PHP version.
Check Apache PHP module:
apachectl -M | grep php
12. Why Compile Instead of Using PECL?
Some users prefer PECL, but Phalcon is usually built from source because:
- PECL may not have the latest version
- You can build for your specific system
- Better compatibility with newer PHP releases
13. Alternative Installation: Using apt Repository
Some third-party repositories provide ready-made Phalcon packages.
For example:
sudo add-apt-repository ppa:phalcon/stable
sudo apt update
sudo apt install php-phalcon
This avoids manual compilation.
14. Understanding How Phalcon Works Internally
Phalcon works differently from traditional frameworks:
14.1 Compiled as C Extension
Instead of loading PHP files on every request, Phalcon is compiled into a .so extension.
14.2 Memory Optimization
Because it runs in memory as a shared extension, Phalcon applications consume fewer resources.
14.3 Faster MVC Execution
Its MVC components (router, dispatcher, etc.) are optimized at the C level.
15. Working With Phalcon After Installation
After installation, you can start building applications.
15.1 Directory Structure
Typical Phalcon project has:
/app/controllers/app/models/app/views/public
15.2 Sample Controller
<?php
class IndexController extends \Phalcon\Mvc\Controller {
public function indexAction() {
echo "Hello from Phalcon!";
}
}
16. Updating Phalcon Later
To update Phalcon:
- Pull latest source:
git pull origin master - Rebuild:
sudo ./install
17. Removing Phalcon
If you want to remove the extension:
sudo phpdismod phalcon
sudo rm /etc/php/*/mods-available/phalcon.ini
sudo rm /usr/lib/php/*/phalcon.so
Restart PHP afterwards.
Leave a Reply