As a developer I spend countless hours on the computer. Over time I accumulate a ton of cruft. Everything from old forgotten files, unused apps, and worst of all hidden junk that has been installed by following some random tutorial.

This past weekend I decided it was finally time to wipe my Macbook’s hard drive and start fresh. I have used it daily for several years now and still had artifacts from when I used Mamp. Since then Vagrant has turned to my local server of choice and one of the reasons is how clean you can keep your machine by utilizing it.

After finishing the new Mac OS X install it felt like a new beginning. So clean, so minimal. I’ve missed that.

This go around I wanted to keep it as minimal as possible and only install things I know I need and use. This tutorial covers how I set up my Mac for local PHP Development.

ZSH Shell

ZSH is a bash alternative and can be easily installed using an open source project named “Oh My ZSH”. I prefer this route because it has numerous plugins and themes that come preinstalled. So customizing is easy.

Their site will give you instructions for installing and it’s all done automatically via a curl or wget call.

Since mine was a fresh machine this took a while to install because it also handles any requirements. Git, Xcode, etc. Just follow the on-screen instructions until it finishes.

Homebrew and PHP

The next step is to get PHP running on the local machine. It is needed for local PHP so later running a linter, composer, etc is all available to my apps.

Homebrew, labeled as the missing package manager for OS X, allows you to easily install items that are not standard from Apple.

You can install Homebrew by running the following terminal command:

ruby -e "$(curl -fsSL"

Just as before, follow the on-screen steps until it completes.

Once it finishes, move on to installing PHP:

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

These commands will setup a very basic php 5.6 without a lot of the items that typically come installed like Apache, fpm, ldap, MySQL, etc.


Composer is the PHP package manager. Almost all frameworks and packages are now using it to handle dependencies so it’s good to have it installed locally.

We can easily install it by running the following in terminal:

curl -sS | php

After it completes move the composer.phar executable into your terminals $PATH:

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

After this you may have to restart terminal but you should be able to run composer and get a list of available commands.


Vagrant is a tool for building a local virtual development environment. It allows you to run another operating system within your current one. The advantages to using a virtual machine is that everything is self contained.

If you make a mistake, just destroy the machine.

Another use case is you can mirror your production server which will allow you to confidently ensure you are developing to the same requirements.

To give you an example, a few years ago PHP changed it’s array syntax and any old array code would continue to work. However, the new style would throw out a nasty error if the PHP version running didn’t support it. By having your local machine mirror production you can instantly see the error of your ways.

Installing Vagrant is really simple as they offer binaries for Mac OS X, Windows, and Linux. Just head over to their site and download the one that’s right for you.

After it installs it’s time to setup a new Vagrant box and I choose to use Homestead by Laravel.


Homestead is created by Laravel but it’s not specific to the framework. You can run any PHP app on it.

What I enjoy about Homestead is that it allows you to create a virtual machine in the style you like. Most Vagrant tutorials recommend you have a machine for each of your apps but I came from using Mamp and I like having one master VM with all my apps. That way I can quickly switch between anything at any time.

To setup Homestead run the following terminal command:

vagrant box add laravel/homestead

This downloads a machine image and it’s pretty hefty, so it will take a few minutes based on your internet speed.

While it’s downloading I open a new terminal tab and create a new Code directory to hold all my apps:

mkdir ~/Code

Next cd into Code and clone the Homestead git repo:

git clone Homestead

Now, cd into Homestead and run its installer:


This file does is create a new directory at ~/.homestead with a yaml file for app settings and two extra files for basic settings. These are and aliases.

Now open ~/.homestead/Homestead.yaml in your favorite editor. The part we are concerned about is the folders, sites, and databases.

Folders are where your code is located on your machine. By default it is ~/Code just as we created earlier.

Sites are your local apps. For example if I wanted my next app to be cakesandpies then I’d use:

    - map:
      to: /home/vagrant/Code/cakesandpies/public

What this basically says is, map the url to the directory specified. Homestead uses this to create a vhost on the virtual machine to match them up.

Finally in the databases section you can list out any you want automatically created.

    - homestead
    - cakesandpies

Now save this file and it’s time to get it all running. cd into ~/Code/Homestead and run vagrant up. A short while later it should say it’s up and running.

Before we can access our app from the browser we will need to add a local domain to our hosts file. Open /etc/hosts in your favorite editor and add a new line at the bottom:

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

Save it and now create a new file at ~/Code/cakesandpies/public/index.php and enter this text:

echo 'Cakes and Pies!';

Now hit the url in your browser. Be sure and append the port of 8000 which is Homestead’s default.

If all went as planned you should see “Cakes and Pies!”.


These steps will hopefully allow you to get a fresh machine up and running for PHP development pretty easily. If you have any questions feel free to comment below or hit me up on Twitter. A huge thank you to Taylor Otwell and his Gist for making this easy.

20 thoughts on “ How to set up your Mac for local PHP Development ”

  1. Mac and development environments works like a charm.
    Porting everything for Windows environments is a real challenge 😦

    Thanks for the article !!!


      1. Sure… But I think that mapping is the other way… It’s mapping external port 80 to internal port 8000… So if you just hit the URL you’ve setup in your hosts file you should see the site without needing to add a port to the address


  2. I prefer installing composer globally with homebrew. When you start a new project or something your don’t need to download it.
    Plus, composer update looks better than php composer.phar update 😀


  3. This is timely and pretty cool. I just got a Mac for PHP development this week. Switching from Linux and a Windoze/Cygwin development environment, this is a really helpful post!


    1. Yes, WordPress installs should “just work”. The only difference is in setting up your vhost to point to the base install instead of say /public. I run a local copy of all my WordPress on this setup.


  4. Hi, there is no mention of Virtualbox in this tut unless Im mistaken, Im upto “vagrant up” and it errors asking for virtualbox, I have installed virtualbox now, but how do I link it to the Homestead box already installed


  5. Hi Eric, I got it going by linking virtualbox to my homestead box. great tutorial by the way thank you! I followed everything but i should have installed virtualbox before vagrant then i would have been ok. All good now cheers


  6. Something is wrong with my installation process, I did everything in given order, but I see no output on or


  7. Hi Eric, it was a nice article. People usually limit Homestead to Laravel but its a great idea to use it for other projects as well. Even other languages can be used. I found Homestead.Yaml a bit hard to understand at first because documentation is only focused on Shared Folders and Sites and there is limited explanation on multiple sites and multiple shared folders. I have explained the whole Homestead.YAML file from top to bottom here


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s