In part 2 of this CakePHP 3 tutorial we will start by firing up a Vagrant development box to act as our web-server for the rest of the series, we'll then install CakePHP 3 onto this virtual machine. At this stage you should have Vagrant, VirtualBox and maybe Git installed on your computer, we will be making use of these from now on.

We'll start by creating a virtual machine to act as our web server. As mentioned previously, we will be making use of Vagrant to manage a virtual development machine for us. The nuts and bolts of Vagrant would need multiple posts to describe, but simply put, Vagrant uses a simple text file to define a virtual machine which can be managed from a command line.

Going hand-in-hand with Vagrant is a number of provisioning tools (Such as Puppet, Chef and Ansible). These provisioning tools are incredibly powerful tools that allow for the configuration and automation of server creation and management. In a large, scalable application you could create a configuration file once, and if you require an extra server you simply run the provisioning tool and it will do all the hard work for you.

For this tutorial we will be using Puppet since it is the only one of the three tools that can easily be run on a Windows machine. However, if you are running Linux or OS X, take a good look at Ansible or Chef!

PuPHPet is an online tool that gives an easy to use graphical interface for creating a Vagrant and Puppet configuration. You can go and play around on the PuPHPet website, but for the sake of brevity I've created a configuration for you to download. You can download it from

If you are running Linux or OS X take a look at the FriendsOfCake vagrant boxes (Ansible: and Chef:, especially the Ansible one. They are incredibly easy to use (Even easier than PuPHPet) - but they don't support Windows.

After you've downloaded it, unzip the file into a events directory which you can locate anywhere on your computer. This will be the directory that we will use for the rest of this series. In this directory you should have a Vagrantfile file, and a puphpet directory. Inside the puphpet directory there is a config.yaml file, you can upload this file to the PuPHPet website to change the configuration if you want.

Open up a terminal or command line (In Windows, run cmd.exe), for most of this tutorial we will be working in the command line.

Before we start the Vagrant box we are going to install a Vagrant plugin that will automatically create the hostname for you when the box is started. Simply run vagrant plugin install vagrant-hostsupdater. The next step is bringing our new Vagrant box online and to start some real development. Simply run vagrant up from inside your events directory, you might be asked for your password, this is normal and part of the Hosts Updater plugin. Vagrant will download a Debian 7.5 based virtual machine (Which may take some time). After that, it will start the virtual machine and Puppet will take over and install everything. This can take a couple of minutes (Depending on the speed of your internet connection and your computer), so grab a cup of coffee, sit back and relax!

When Vagrant is done doing it's thing, run vagrant status to make sure it's working correctly. You should see

$ vagrant status
Current machine states:

default                   running (virtualbox)

The VM is running. To stop this VM, you can run `vagrant halt` to
shut it down forcefully, or you can run `vagrant suspend` to simply
suspend the virtual machine. In either case, to restart it again,
simply run `vagrant up`.

In order to actually access the machine, you need to modify your hosts file. In linux you'll find it in /etc/hosts, OS X it's /private/etc/hosts and windows it's c:\windows\system32\drivers\etc\hosts, add the following to it if it is not already there:

Now we've got our server running, it is time to SSH into it and create our CakePHP 3 project. In your terminal window run vagrant ssh. You'll see the following output:

Linux packer-virtualbox-iso 3.2.0-4-amd64 #1 SMP Debian 3.2.57-3 x86_64
Welcome to your Vagrant-built virtual machine.
You have mail.
Last login: Thu Jul 17 17:19:20 2014 from

[07:27 AM]-[vagrant@events]-[~] 

Next up is to start our actual project. CakePHP 3 makes use of Composer for managing dependencies and creating new projects, navigate to the /vagrant directory on the Vagrant box and run:

/vagrant $ rm -rf events

to clear out any existing code that may interfere.

/vagrant $ composer create-project --prefer-dist -s dev cakephp/app events

If this is the first time you've ever used composer, or the first time you've used composer create-project you might be wondering "what on earth just happened". Let's unpack it a bit.

First we ran rm -rf events to remove the events directory that was created automatically by Vagrant. This is because composer requires the directory to be empty, or non-existent. Then we ran composer create-project --prefer-dist -s dev cakephp/app events which tells composer that you wish to create a new project called events (which will be the directory name) based on the cakephp/app composer package. --prefer-dist means that you would prefer composer download the packaged version of the composer package (i.e. a zip file) instead of getting the full source code, this is almost always faster. -s dev tells composer that you will accept packages with a stability level of dev, or higher (Available options are dev, alpha, beta, RC, stable). The reason for using it here is that CakePHP 3 is still under development and we want to make sure we have the latest version of the CakePHP 3 code.

Composer makes use (by default) of the repository to determine where to locate the requested packages. Since we are creating a project based on cakephp/app, composer will query for the cakephp/app package, will return the source repository where composer can download the_ cakephp/app_ package from. Composer will then download the package. The next step is for composer to determine the dependencies for cakephp/app (using the composer.json file), and download those dependencies. After all the dependencies are installed, some file permissions set and the initial configuration file is created.

We can then navigate to our webroot directory and look at it's contents:

$ cd /var/www

/var/www $ ls  bin/  composer.json  composer.lock  config/  index.php  logs/  phpunit.xml.dist  plugins/  src/  tests/  tmp/  vendor/  webroot/

If you see all those files, navigate to in your browser of choice, and as long as everything worked as expected, you should see some beautiful cake!


Don't worry about the database error yet, we will get around to configuring that in Part 3.

Before we finish with part 2, run exit to exit the vagrant ssh session and then run vagrant halt to shut the virtual machine down.

In part 3, we will connect to the database, create a migration and starting doing some real baking!