Installation¶

Requirements¶

PHP 8.0¶

Phalcon v5.5 supports only PHP 8.0 and above.

Although PHP 8.0 was released several years ago and it's active support as well as security updates have expired, Phalcon still supports it, in order to offer enough time for developers to upgrade their applications. We will continue to support PHP 8.0 for v5 for another year. Phalcon v6 and later will support PHP 8.1+.

NOTE

Installing a web server is outside the scope of this document. Please refer to relevant guides on the Internet on how to install a web server.

PDO¶

Since Phalcon is loosely coupled, it exposes functionality without the need for additional extensions. However, certain components rely on additional extensions to work. When in need of database connectivity and access, you will need to install the php_pdo extension. If your RDBMS is MySQL/MariaDB or Aurora, you will need the php_mysqlnd extension also. Similarly, using a PostgreSql database with Phalcon requires the php_pgsql extension.

Load order¶

Phalcon needs to be loaded after PDO. Some distributions add a number prefix on ini files. If that is the case, choose a high number for Phalcon (e.g. 50-phalcon.ini), higher than PDO. This will load Phalcon after the prerequisite extensions. If however, your distribution only has a php.ini file, please make sure that the order is similar to this:

extension=pdo.so
extension=phalcon.so

Hardware¶

Phalcon is designed to use as few resources as possible while offering high performance. Although we have tested Phalcon in various high-end environments, (such as 0.25GB RAM, 0.5 CPU), the hardware that you will choose will depend on your application needs.

We have hosted our website and blog for the last few years on an Amazon VM with 512MB RAM and 1 vCPU.

Software¶

NOTE

You should always try and use the latest version of Phalcon and PHP as both address bugs, security enhancements as well as performance.

Along with PHP 8.0 or greater, depending on your application needs and the Phalcon components you need, you might need to install the following extensions:

curl
fileinfo
gettext
gd2 (to use the Phalcon\Image\Adapter\Gd class)
imagick (to use the Phalcon\Image\Adapter\Imagick class)
json
libpcre3-dev (Debian/Ubuntu), pcre-devel (CentOS), pcre (macOS)
PDO Extension as well as the relevant RDBMS-specific extension (i.e. MySQL, PostgreSql, etc.)
OpenSSL Extension
Mbstring Extension
Memcached or other relevant cache adapters depending on your usage of cache

NOTE

Installing these packages will vary based on your operating system as well as the package manager you use (if any). Please consult the relevant documentation on how to install these extensions.

For the libpcre3-dev package you can use the following commands:

PCRE¶

Debian¶

sudo apt-get install libpcre3-dev

and then try and install Phalcon again

CentOS¶

sudo yum install pcre-devel

Mac/Osx using Brew¶

brew install pcre

Without brew, you need to go to the PCRE website and download the latest pcre:

tar -xzvf pcre2-10.42.tar.gz
cd pcre2-10.42
./configure --prefix=/usr/local/pcre-10.42
make
make install
ln -s /usr/local/pcre2-10.42 /usr/sbin/pcre
ln -s /usr/local/pcre2-10.42/include/pcre.h /usr/include/pcre.h

For Maverick

brew install pcre

if it gives you an error, you can use

sudo ln -s /opt/local/include/pcre.h /usr/include/
sudo pecl install apc

Installation Platforms¶

Since Phalcon is compiled as a PHP extension, its installation is somewhat different from any other traditional PHP framework. Phalcon needs to be installed and loaded as a module on your web server.

NOTE

The preferred method of installation is through PECL.

NOTE

To install phalcon with PECL you will need at least 4GB of RAM, otherwise the PECL build command will fail.

PECL¶

The PECL installation method is available for Windows, Linux, and macOS. Under Windows pre-compiled dll files are available, while under Linux and macOS, Phalcon will be compiled locally. To install Phalcon using PECL make sure you have pecl/pear installed.

pecl channel-update pecl.php.net
pecl install phalcon

Additional PPA¶

Linux DEB: Ondřej Surý¶

You can install the repository offered by Ondřej Surý.

Installation of the repo:

sudo add-apt-repository ppa:ondrej/php
sudo apt-get update

and Phalcon:

sudo apt-get install php-phalcon5

Linux RPM: Remi¶

Remi Collet maintains an excellent repository for RPM-based installations. You can find instructions on how to enable it for your distribution here.

Installing Phalcon after that is as easy as:

yum install php80-php-phalcon5

Additional versions are available both architecture-specific (x86/x64) and PHP version specific

FreeBSD/GhostBSD¶

Binary package (pkg) and compile from source (ports) are available for FreeBSD. To install it you will need to issue the following commands:

pkg¶

pkg install php80-phalcon5

ports¶

cd /usr/ports/www/phalcon5

make install clean

Gentoo¶

An overlay for installing Phalcon can be found here

Raspberry Pi¶

sudo -s
git clone https://github.com/phalcon/cphalcon
cd cphalcon/
git checkout tags/v5.5.0 ./
zephir fullclean
zephir build

It is also necessary to increase the swap file from the default 100 MB to at least 2000 MB. Because the compiler lacks RAM.

sudo -s
nano /etc/dphys-swapfile

Replacing CONF_SWAPSIZE=100 with CONF_SWAPSIZE=2000

After saving the setting, restart the daemon:

/etc/init.d/dphys-swapfile stop
/etc/init.d/dphys-swapfile start

macOS¶

Brew includes binary packages, so you don't need to compile Phalcon yourself. If you want to compile the extension yourself you need the following dependencies installed:

Compilation requirements¶

PHP 8.x development resources
XCode

Brew¶

Binary installation (preferred):

brew tap phalcon/extension https://github.com/phalcon/homebrew-tap
brew install phalcon

Compile phalcon:

brew tap phalcon/extension https://github.com/phalcon/homebrew-tap
brew install phalcon --build-from-source

MacPorts¶

sudo port install php80-phalcon

Edit your php.ini file and then append at the end:

extension=php_phalcon.so

Restart your webserver.

PHPBrew (macOS/Linux)¶

PHPBrew is an excellent way to manage multiple versions of PHP and PHP extensions on your system(s). Installation instructions for PHPBrew can be found here

If you're using PHPBrew, you can install Phalcon using the following:

sudo phpbrew ext install phalcon

Windows¶

To use Phalcon on Windows, you will need to install the phalcon.dll. We have compiled several DLLs depending on the target platform. The DLLs can be found on our download page.

Identify your PHP installation as well as architecture. If you download the wrong DLL, Phalcon will not work. phpinfo() contains this information. In the example below, we will need the NTS version of the DLL:

phpinfo

The available DLLs are:

Architecture	Version	Type
x64	8.x	Thread safe
x64	8.x	Non Thread safe (NTS)
x86	8.x	Thread safe
x86	8.x	Non Thread safe (NTS)

Edit your php.ini file and then append at the end:

extension=php_phalcon.dll

Restart your webserver.

Compile From Sources¶

Compiling from source is similar to most environments (Linux/macOS).

Requirements¶

PHP development resources depending on your version (8.1 recommended)
GCC compiler (Linux/Solaris/FreeBSD) or Xcode (macOS)
re2c >= 0.13
libpcre-dev

Compilation¶

If you wish to compile Phalcon you can do so by using Zephir. You will first need to have the Zephir Parser installed in your system:

pecl install zephir_parser

Depending on your target system, you might need to create a zephir_parser.ini file, to load this extension. The contents of the file should be:

extension=zephir_parser.so

and you might need to enable the extension using phpenmod

phpenmod zephir_parser

You will then need to download the latest zephir.phar from here. Move the file to a folder that is available in your PATH, such as /usr/local/bin for example, and make it executable:

mv zephir.phar /usr/local/bin 
cd /usr/local/bin/
mv zephir.phar zephir 
chmod a+x zephir

You might also need to change the ownership of the file, depending on your environment.

NOTE

Zephir can also be installed using composer require phalcon/zephir:dev-development

Clone the repository to a location on your file system.

git clone https://github.com/phalcon/cphalcon

Compile Phalcon

cd cphalcon/
git checkout tags/v5.5.0 ./
zephir fullclean
zephir build

Check the module

php -m | grep phalcon

You will now need to enable Phalcon. Create a file called phalcon.ini with extension=phalcon.so as its content. The file should be present in:

Suse: /etc/php8/conf.d/phalcon.ini
CentOS/RedHat/Fedora: /etc/php.d/phalcon.ini
Ubuntu/Debian with Apache2: /etc/php8/apache2/conf.d/30-phalcon.ini with this Content:
Ubuntu/Debian with Php8-FPM: /etc/php8/fpm/conf.d/30-phalcon.ini
Ubuntu/Debian with Php8-CLI: /etc/php8/cli/conf.d/30-phalcon.ini

For PHP 8.+ the above paths might differ slightly.

The instructions above will compile and install the module on your system. You can also compile the extension and then add it manually in your ini file:

cd cphalcon/
git checkout tags/v5.5.0 ./
zephir fullclean
zephir compile
cd ext
phpize
./configure
make && make install

If you use the above method you will need to add the extension=phalcon.so in your php.ini both for CLI and the web server.

Tuning Build¶

By default, we compile to be as compatible as possible with all processors (gcc -mtune=native -O2 -fomit-frame-pointer). If you would like to instruct the compiler to generate optimized machine code that matches the processor where it is currently running you can set your own compile flags by exporting CFLAGS before the build. For example

export CFLAGS="-march=native -O2 -fomit-frame-pointer"
zephir build

This will generate the best possible code for that chipset but will likely break the compiled object on older chipsets.

Shared Hosting¶

Running your application on shared hosting might restrict you from installing Phalcon, especially if you do not have root access. Some web hosting control panels luckily have Phalcon support.

cPanel & WHM¶

cPanel & WHM support Phalcon using Easy Apache 4 (EA4). You can install Phalcon by enabling the module in Easy Apache 4 (EA4).

Plesk¶

The plesk control panel doesn't have Phalcon support, but you can find installation instructions on the Plesk website