By Bruno Skvorc

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!

  • alantonilopez

    Nice tip, good to see Phalcon 2 taking shape

  • Aleksander Koko

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

  • 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.

    • 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 ( 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 :)

        • 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…

          • No problem :)

      • oh by the way, i’m on mac os x yosemite beta. maybe that’s got something to do with it, i’m not sure. normally VM is a seperate environment but stil…

  • OsakaWebbie

    Quote: “If you read this when Phalcon is already in a mature 2.x stage, let us know and we’ll update the post.” Okay, this is your notification – it’s August 2015, Phalcon 2.0 has been released (April, IIRC), and I’m reading this with interest.

    I’d love it if you’d also include more about how to do it with CentOS instead of Ubuntu. I want to set up a Vagrant box to similate a future production environment on a hosted VPS, so CentOS is more common in that scenario.

Get the latest in Front-end, once a week, for free.