Quick Tip: Install Zephir and Phalcon 2 on Vagrant

Bruno Skvorc
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: homestead.app
      to: /home/vagrant/Code/Laravel/public
    - map: test.app
      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 https://github.com/json-c/json-c.git
cd json-c
sh autogen.sh
make && sudo make install

git clone https://github.com/phalcon/zephir
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 http://github.com/phalcon/cphalcon
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 "extension=phalcon.so" >> /etc/php5/fpm/conf.d/20-phalcon.ini
echo "extension=phalcon.so" >> /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 https://github.com/phalcon/website 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/test.app (or x.app where x is the name of your virtual host defined in Homestead.yaml) with the following:

server {

    listen   80;
    server_name test.app;

    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/test.app-error.log 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 http://test.app:8000 (or any other virtual host URL you defined, if you didn’t use test.app like I did above.

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