Welcome to the incredibly popular Easy Laravel 5 companion blog. To celebrate the new edition's release (updated for Laravel 5.5!) use the discount code easteregg to receive 20% off the book or book/video package! » Buy the book
PHP is only one of several technologies you'll need to have access to in order to begin building Laravel-driven web sites. Additionally you'll need to install a web server such as Apache or nginx, a database server such as MySQL or PostgreSQL, and often a variety of supplemental technologies such as Redis and Grunt. As you might imagine, it can be quite a challenge to install and configure all of these components, particularly when you'd prefer to be writing code instead of grappling with configuration issues.
In recent years the bar was dramatically lowered with the advent of the virtual machine. A virtual machine is a software-based implementation of a computer that can be run inside the confines of another computer (such as your laptop), or even inside another virtual machine. This is an incredibly useful bit of technology, because you can use a virtual machine to for instance run Ubuntu Linux inside Windows 7, or vice versa. Further, it's possible to create a customized virtual machine image preloaded with a select set of software. This image can then be distributed to fellow developers, who can run the virtual machine and take advantage of the custom software configuration. This is precisely what the Laravel developers have done with Homestead, a Vagrant-based virtual machine which bundles everything you need to get started building Laravel-driven websites.
Homestead is currently based on Ubuntu 14.14, and includes everything you need to get started building Laravel applications, including PHP 5.6, Nginx, MySQL, PostgreSQL and a variety of other useful utilities. It runs flawlessly on OS X, Linux and Windows, and Vagrant configuration is pretty straightforward, meaning in most cases you'll have everything you need to begin working with Laravel in less than 30 minutes.
Homestead requires Vagrant and VirtualBox. User-friendly installers are available for all of the common operating systems, including OS X, Linux and Windows. Take a moment now to install Vagrant and VirtualBox. Once complete, open a terminal window and execute the following command:
$ vagrant box add laravel/homestead ==> box: Loading metadata for box 'laravel/homestead' box: URL: https://vagrantcloud.com/laravel/homestead ==> box: Adding box 'laravel/homestead' (v0.2.2) for provider: virtualbox box: Downloading: https://vagrantcloud.com/laravel/boxes/homestead/ versions/0.2.2/providers/virtualbox.box ==> box: Successfully added box 'laravel/homestead' (v0.2.2) for 'virtualbox'!
This command installs the Homestead box. A box is just a term used to refer to a Vagrant package. Packages are the virtual machine images that contain the operating system and various programs. The Vagrant community maintains a variety of boxes useful for different applications, so check out this list of popular boxes for an idea of what else is available.
Once the box has been added, you'll next want to install the Homestead CLI tool. To do so, you'll use Composer:
$ composer global require "laravel/homestead=~2.0" Changed current directory to /Users/wjgilmore/.composer ./composer.json has been updated Loading composer repositories with package information Updating dependencies (including require-dev) - Installing symfony/process (v2.6.3) Downloading: 100% - Installing laravel/homestead (v2.0.8) Downloading: 100% Writing lock file Generating autoload files
After this command has completed, make sure your
~/.composer/vendor/bin directory is available within your system PATH. This is because the
laravel/homestead package includes a command-line utility (named
homestead) which you'll use to create your Homestead configuration directory:
$ homestead init Creating Homestead.yaml file... ok Homestead.yaml file created at: /Users/wjgilmore/.homestead/Homestead.yaml
Next you'll want to configure the project directory that you'll share with the virtual machine. Doing so requires you to identify the location of your public SSH key, because key-based encryption is used to securely share this directory. If you don't already have an SSH key and are running Windows, this SiteGround tutorial offers a succinct set of steps. If you're running Linux or OS X, nixCraft offers a solid tutorial.
You'll need to identify the location of your public SSH key in the
Homestead.yaml file. Open this file and locate the following line:
If you're running Linux or OS X, then you probably don't have to make any changes to this line because SSH keys are conventionally stored in a directory named
.ssh found in your home directory. If you're running Windows then you'll need to update this line to conform to Windows' path syntax:
If you're running Linux or OS X and aren't using the conventional SSH key location, or are running Windows you'll also need to modify
keys accordingly. For instance Windows users would have to update this section to look something like this:
keys: - c:/Users/wjgilmore/.ssh/id_rsa
Next you'll need to modify the
folders list to identify the location of your Laravel project (which we'll create a bit later in this chapter). The two relevant
Homestead.yaml settings are
sites, which by default look like this:
folders: - map: ~/Code to: /home/vagrant/Code sites: - map: homestead.app to: /home/vagrant/Code/Laravel/public
It's this particular step that tends to confuse most Homestead beginners, so pay close attention to the following description. The
map attribute identifies the location in which your Laravel project will be located. The default value is
~/Code, meaning Homestead expects your project to reside in a directory named
Code found in your home directory. You're free to change this to any location you please, keeping in mind for the purposes of this introduction the directory must be your Laravel project's root directory (why this is important will become apparent in a moment). The
to attribute identifies the location on the virtual machine that will mirror the contents of the directory defined by the
map key, thereby making the contents of your local directory available to the virtual machine.
map attribute defines the domain name used to access the Laravel application via the browser. Leave this untouched for now. Finally, the
to attribute defines the Laravel project's root web directory, which is
/public by default. This isn't just some contrived setting; not only is
/public the directory you would need to configure when setting up a web server to serve a Laravel application, but
/home/vagrant/Code/Laravel/public is also the directory that Homestead's nginx web server has been configured to use! This means that the path defined by the
map attribute must contain a directory named
Laravel, and inside that a directory named
public. If you do not do this you'll receive the dreaded 404 error when attempting to access the application via your browser.
If this explanation is clear as mud, let's clarify with an example. Begin by setting the
map attribute to any path you please, likely somewhere within the directory where you tend to manage your various software projects. For instance, mine is currently set like this:
folders: - map: /Users/wjgilmore/Software/dev.todoparrot.com - to: /home/vagrant/Code
Next, create a directory named
Laravel inside the directory identified by the
map attribute, and inside it create a directory named
public. Create a file named
index.php inside the
public directory, adding the following contents to it:
<?php echo "Hello from Homestead!"; ?>
Save these changes, and then run the following command:
$ homestead up Bringing machine 'default' up with 'virtualbox' provider... ==> default: Importing base box 'laravel/homestead'... ==> default: Matching MAC address for NAT networking... ==> default: Checking if box 'laravel/homestead' is up to date... ... ==> default: Forwarding ports... default: 80 => 8000 (adapter 1) default: 443 => 44300 (adapter 1) default: 3306 => 33060 (adapter 1) default: 5432 => 54320 (adapter 1) default: 22 => 2222 (adapter 1) $
Your Homestead virtual machine is up and running! Open a browser and navigate to the URL
http://homestead.app and you should see
Hello from Homestead!. Note the use of the
8000 port in the URL. This is because the Homestead virtual machine forwards several key ports to non-standard port numbers, allowing you to continue using the standard ports locally. I've included the list of forwarded ports in the debug output that followed the
vagrant up command. As you can see, port 80 (for HTTP) forwards to 8000, port 3306 (for MySQL) forwards to 33060, port 5432 (for PostgreSQL) forwards to 54321, and port 22 (for SSH) forwards to 2222.
If the virtual machine did not start, or if you do not see
Hello from Homestead! when accessing
http://homestead.app, then double-check your
Homestead.yaml file, ensuring all of the paths are properly set.
Remember, we just created the
Laravel/public directory to confirm Homestead is properly configured and able to serve files found in our local development directory. You should subsequently delete this directory as it will be created automatically when we generate the book theme project in the section, "Creating the TODOParrot Application".
Incidentally, if you'd like to shut down the virtual machine you can do so using the following command:
$ homestead destroy
Because Homestead is a virtual machine running Ubuntu, you can SSH into it just as you would any other server. For instance you might wish to tinker with the nginx or MySQL configuration files, install additional software, or make other adjustments to the virtual machine environment. You can SSH into the virtual machine using the
ssh command if you're running Linux or OS X, or using a variety of SSH clients if you're running Windows (My favorite Windows SSH client is PuTTY:
$ ssh firstname.lastname@example.org -p 2222 Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-30-generic x86_64) * Documentation: https://help.ubuntu.com/ System information as of Thu Jan 8 00:57:20 UTC 2015 System load: 0.96 Processes: 104 Usage of /: 5.0% of 39.34GB Users logged in: 0 Memory usage: 28% IP address for eth0: 10.0.2.15 Swap usage: 0% IP address for eth1: 192.168.33.10 Graph this data and manage this system at: https://landscape.canonical.com/ Get cloud support with Ubuntu Advantage Cloud Guest: http://www.ubuntu.com/business/services/cloud Last login: Fri Dec 19 15:01:15 2014 from 10.0.2.2
You'll be logged in as the user
vagrant, and if you list this user's home directory contents you'll see the
Code directory defined in the
vagrant@homestead:~$ ls Code
If you're new to Linux be sure to spend some time nosing around Ubuntu! This is a perfect opportunity to get familiar with the Linux operating system without any fear of doing serious damage to a server because if something happens to break you can always reinstall the virtual machine!
With Homestead installed you can next create the Laravel 5 application. Because at the time I wrote this Laravel 5 hasn't yet been officially released, we'll need to use Composer (PHP's de facto package management solution) to create a new project using Laravel's development branch. In order to ensure the application is properly served by Homestead, enter the
Code directory identified by the
map attribute, delete the
Laravel directory and the test script, and then execute the following command:
$ composer create-project laravel/laravel Laravel dev-develop Installing laravel/laravel (dev-develop 083db95...dac46617) - Installing laravel/laravel (dev-develop develop) Cloning develop ... Compiling views Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]? Y Application key [9UCBk7IDjvAGrkLOUBXw43yYKlymlqE3Y] set successfully.
Once complete, return to your browser, reload
http://homestead.app, and you should see the default Laravel 5 application splash page!