Skip to main content

Quick Tip: Install Zephir and Phalcon 2 on Vagrant

By Bruno Skvorc



Free JavaScript Book!

Write powerful, clean and maintainable JavaScript.

RRP $11.95

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 code auditor from Croatia with Master’s Degrees in Computer Science and English Language and Literature. He's been a web developer for 10 years until JavaScript drove him away. He now runs a cryptocurrency business at via which he makes blockchain tech approachable to the masses, and runs Coinvendor, an on-boarding platform for people to easily buy cryptocurrency. He’s also a developer evangelist for, a San Francisco-based AI-powered machine vision web scraper.

New books out now!

Get practical advice to start your career in programming!

Master complex transitions, transformations and animations in CSS!