Skip to main content

Quick Tip: Install Zephir and Phalcon 2 on Vagrant

By Bruno Skvorc

This quick tip will show you how to install Phalcon on a Homestead Improved instance, and will help you get a sample Phalcon app up and running.

The version of Phalcon we’ll be using in this Quick Tip will be 2.0 – a pre-release. If you read this when Phalcon is already in a mature 2.x stage, let us know and we’ll update the post. To install the stable 1.x version, just run sudo apt-get install php5-phalcon and it should work.

Step 1: HI

Get HI (Homestead Improved) up and running via this quick tip.

Add another site into the vhost configuration so your sites block looks like this:

    - map:
      to: /home/vagrant/Code/Laravel/public
    - map:
      to: /home/vagrant/Code/phalcon_sample/public

Step 2: Install Zephir

Zephir is the language that powers the new Phalcon. Instead of being written in C, Phalcon 2 is written in a mediator language called Zephir, designed solely for building PHP extensions. Find out more about it here.

sudo apt-get update
sudo apt-get install gcc make re2c libpcre3-dev

cd ~/Code
git clone
cd json-c
make && sudo make install

git clone
cd zephir
./install -c

Step 3: Install the Extension

If the VM is not up yet, run vagrant up, then enter the VM via vagrant ssh.

cd ~/Code

git clone
cd cphalcon
git checkout 2.0.0
zephir build

This installs the extension. You still need to activate it by including it in your php.ini file.

sudo su
echo "" >> /etc/php5/fpm/conf.d/20-phalcon.ini
echo "" >> /etc/php5/cli/conf.d/20-phalcon.ini

Let’s check if it installed correctly. Restart nginx and php5-fpm. Run php -i | grep Phalcon. If you get any output at all (e.g. “Author => Phalcon Team”), the installation was a success.

Step 4: Install the Sample Site

We’ll use the Phalcon home page as a sample site.

cd ~/Code
git clone phalcon_sample

Open /app/var/config/config.php and change baseurl to / and debug to 1. BaseURL is misconfigured for an unknown reason, while debug needs to be activated to deactivate the caching component which is currently having problems working properly. This will be fixed in the future, so if you’re reading this any time after August 2014, try it out with the default settings.

Step 5: Change the Nginx configuration

The Nginx configuration of Phalcon is somewhat iffy, so some customization is required. Just replace the contents of /etc/nginx/sites-available/ (or where x is the name of your virtual host defined in Homestead.yaml) with the following:

server {

    listen   80;

    set $root_path '/home/vagrant/Code/phalcon_sample/public';
    root $root_path;

    index index.php index.html index.htm;

    try_files $uri $uri/ @rewrite;

    location @rewrite {
        rewrite ^/(.*)$ /index.php?_url=/$1;

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    access_log off;
    error_log  /var/log/nginx/ error;

    error_page 404 /index.php;

    sendfile off;

    location ~ \.php$ {
	fastcgi_split_path_info       ^(.+\.php)(/.+)$;
	fastcgi_pass unix:/var/run/php5-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;

        fastcgi_param PATH_INFO       $fastcgi_path_info;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    location ~* ^/(css|img|js|flv|swf|download)/(.+)$ {
        root $root_path;

    location ~ /\.ht {
        deny all;

Save, exit, and restart Nginx with sudo service nginx restart.

Step 6: Disable XDebug [optional]

If you get a 502 error when you run the application after Step 5, there’s still an outstanding bug with Xdebug that’s preventing Phalcon 2 from working properly. It being under heavy development means it’ll be resolved shortly, but in the meanwhile, just going into /etc/php5/mods-available/xdebug.ini and commenting out the contents, then restarting with sudo service php5-fpm restartshould solve things for you.

Wrapping up

That’s it. You can now visit the site in your host’s browser by running (or any other virtual host URL you defined, if you didn’t use like I did above.

Feel free to start hacking away and experimenting on Zephir and Phalcon 2.0 code now!

Bruno is a blockchain developer and technical educator at the Web3 Foundation, the foundation that's building the next generation of the free people's internet. He runs two newsletters you should subscribe to if you're interested in Web3.0: Dot Leap covers ecosystem and tech development of Web3, and NFT Review covers the evolution of the non-fungible token (digital collectibles) ecosystem inside this emerging new web. His current passion project is, the most advanced NFT system in the world, which allows NFTs to own other NFTs, NFTs to react to emotion, NFTs to be governed democratically, and NFTs to be multiple things at once.

Integromat Tower Ad