Prepare your Mac for local Laravel development

Warning: This content was posted a while ago and may be incorrect by now. Please search for more recent guidance with your preferred search engine.

After first struggling for years with setting up my Mac for local development by trying to update the pre-installed version of PHP and then adding mcrypt, MySQL and whichever other components, I finally started using Homebrew while simultaneously switching from Apache to nginx. This was a huge improvement from what I was used to, but Taylor Otwell gifted us with an even better solution with Laravel Homestead.

Even though it does come with setup instructions, there are many steps involved when starting from scratch. It was also frustrating when things broke during setup, since certain things are assumed from people installing the software. Never assume.

So, I worked through a few separate tutorials and compiled this all-in-one list of what to do. Here we go!

Homebrew

You don’t need to install Homebrew, but it will make installing things like PHP much easier. You can install Homebrew by running the following command in Terminal, following the on-screen instructions to completion:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Alternatively, check brew.sh for an updated string.

PHP

As with Homebrew, you don’t strictly need PHP installed locally, but it does come in handy if you want to use a linter or Composer. Run all of the following commands to install PHP, following any on-screen instructions.

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php
brew install php56 --with-homebrew-curl --without-bz2 --without-apache --without-fpm --without-ldap --without-mysql
brew install mcrypt php56-mcrypt

This installs the latest stable version of PHP 5.6 with just the basic necessities.

Composer

Composer is to PHP, as Homebrew is to OS X – the missing package manager. Most frameworks and packages use it for dependency handling, so it makes sense to install it locally if you want to do anything outside the Homestead environment.

Install it by running the following command in Terminal:

curl -sS https://getcomposer.org/installer | php

When it completes, move the composer.phar executable for global access in Terminals:

sudo mv composer.phar /usr/local/bin/composer

You may need to restart Terminal, but Composer should now be usable.

Virtual Machine

This step caught me by surprise (although the newer Homestead instructions now include this) and probably proves that I’m blonder than I appear… The Vagrant installation instructions mention needing a virtual machine host, but they never explicitly instruct you to install it prior to installing itself.

So, at this stage go ahead and install VirtualBox, or VMware Fusion if you’re able to pay $79 plus another $79 for VMware integration with additional benefits such as increased speed.

Vagrant

Vagrant is used to build local virtual machines through downloadable “boxes”. The main advantage is that your development environment will be completely self-contained and can be recreated on any other computer.

Now simply download the Vagrant binary from their website and double-click the installer.

SSH Key

As you will be using SSH to access your Homestead box, set up an SSH key. In Terminal, run:

ssh-keygen -t rsa

Homestead

Although Homestead is a Laravel product, you should be able to use it for non-Laravel development without any issues.

You’re free to set up a virtual machine for each site you’re working on or one machine for all of them. The choice really comes down to what’s more comfortable for you. I prefer a single machine as I tend to be working on multiple things concurrently.

To install the Homestead Vagrant box run the following command in Terminal:

vagrant box add laravel/homestead

This downloads an image file clocking in at almost 1 GB, so give it a few minutes. Once it’s done you’ll need to install Homestead. You can use any location, but I prefer sticking to the ~/Sites folder. In Terminal:

cd ~/Sites

Now clone the Homestead repository:

git clone https://github.com/laravel/homestead.git Homestead

If you need to use PHP 7.0 specific features, try the new version:

git clone -b php-7 https://github.com/laravel/homestead.git Homestead

Once the clone operation is complete, run:

cd ~/Sites/Homestead
bash init.sh

This script creates the ~/.homestead/Homestead.yaml configuration file. Open this file in your editor of choice to configure the folders, sites and databases.

The folders section lists all the local folders you wish to share with the virtual machine. If you choose to use the ~/Sites folder, simply change ~/Code to ~/Sites – or whatever folder you’ll be using.

The sites section is where you configure all the local sites you’ll be working on. For example:

sites:
- map: local.myapp.com
  to: /home/vagrant/Sites/myapp/public

Homestead uses this information to set up the site on nginx on the virtual machine for you.

Lastly, you’ll need to declare any databases you require in the databases section.

databases:
- myapp

Save the file and run vagrant up from the ~/Sites/Homestead folder in the Terminal. You should receive a message once it’s up and running.

Alternatively, you can use Vagrant Manager if you’d prefer to have a handy menubar app.

In order to access our Homestead sites from a browser, we will need to add the domains from the Homestead.yaml file into the local hosts file. Open /etc/hosts in your editor, adding a line for each site to the end of the file and saving it.

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost 

127.0.0.1 local.myapp.com

Alternatively, you can use Gas Mask which allows you to more effectively manage your hosts file.

By default Homestead serves sites on port 8000, but you can make it use port 80 by using the IP address from the Homestead.yaml file, for example:

192.168.10.10 local.myapp.com

To test your new site, create a file at ~/Sites/myapp/public/index.php with the following content:

<?php
echo 'Hello World!'{semicolon}

Now visit the address in your browser.

http://local.myapp.com

Remember to add port 8000 if you used 127.0.0.1 in your hosts file.

http://local.myapp.com:8000

You should see “Hello World!”, if everything went according to plan.