Quick Tip: Install Zephir and Phalcon 2 on Vagrant


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!

Get your free chapter of Level Up Your Web Apps with Go

Get a free chapter of Level Up Your Web Apps with Go, plus updates and exclusive offers from SitePoint.

  • alantonilopez

    Nice tip, good to see Phalcon 2 taking shape

    • http://www.bitfalls.com/ Bruno Skvorc


  • Aleksander Koko

    Happy to see Phalcon tutoial. I think we need more on Phalcon.

    • http://www.bitfalls.com/ Bruno Skvorc

      Working on it :)

  • Onur

    this is my 2nd attempt to set up a local phalcon environment and again, it failed. i get 502 bad gateway with the error

    2014/08/26 21:32:34 [error] 15590#0: *3 recv() failed (104: Connection reset by peer) while reading response header from upstream, client:, server: phalcon.vh, request: “GET / HTTP/1.1″, upstream: “fastcgi://unix:/var/run/php5-fpm.sock:”, host: “phalcon.vh:8000″

    i use laravel on the same vm with the same homestead configuration and it works like a charm.

    • http://www.bitfalls.com/ Bruno Skvorc

      Did you follow the instructions to the letter? Using the same Homestead Improved instance as the one in the post above?

      • Onur

        after failing with my already set up homestead VM, i set up a fresh one with the instructions from above. same result.

        the host works and i can open the static files (images, css etc.) via url. it fails when i try to run the site. this solution (http://stackoverflow.com/questions/23443398/nginx-error-connect-to-php5-fpm-sock-failed-13-permission-denied) does not apply because mine is not “not connecting”, it’s “connection reset by peer”. something happens after php/phalcon starts the script. guess i’ll go back to laravel :)

        • http://www.bitfalls.com/ Bruno Skvorc

          Sorry about that, forgot to mention you need to turn Xdebug off currently! Will update the post!

          • Onur

            it worked! yay! let’s play with it.

            thanks for the tutorial and extra help, it’s much appreciated…

          • http://www.bitfalls.com/ Bruno Skvorc

            No problem :)