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 http://waltherlalk.com/uploads/cakephp_tutorial_puphpet.zip.
If you are running Linux or OS X take a look at the FriendsOfCake vagrant boxes (Ansible: https://github.com/FriendsOfCake/vagrant-ansible and Chef: https://github.com/FriendsOfCake/vagrant-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 10.0.2.2 [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 packagist.org repository to determine where to locate the requested packages. Since we are creating a project based on cakephp/app, composer will query packagist.org for the cakephp/app package, packagist.org 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 README.md 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 http://events.dev 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!