Getting Started with Craft CMS 2 and Laravel Valet

Using Craft CMS 3? Check out my Craft 3 specific article.

Laravel Valet is a local development environment for macOS users that was created with speed, ease-of-use, flexibility, and simplicity in mind. Valet is basically a local server built with nginx, php, and dnsmasq that runs by itself whenever your computer starts. That means that once you get it setup, (for the most part) you’ll never have to bother with it again! Laravel Valet works out-of-the-box with quite a few modern platforms, including Craft CMS, Wordpress, Statamic, Laravel apps, static files, and more. All in all, it’s a great solution if you’re looking for something a bit smaller in size and easier to manager than something like Vagrant or Docker.

In order to use Valet, we’re going to need to install and setup some other development tools along the way. This will involve some command line work, but trust me, it’s not as hard as it seems! If you feel like you’re not very comfortable with the terminal I recommend sharpening up your skills with Wes Bos’s wonderful (and free!) Command Line Power User course.

Brew all the things!

Alright, first things first — we’re going to need to install Homebrew. Think of Homebrew as a package manager for your Mac, similar to NPM for Javascript or Composer for PHP. It simplifies the process of installing pretty much anything on your Mac. Honestly, if you’re not already using Homebrew, you’re really missing out.

So go ahead and launch Terminal on your mac (alternatively if you use a program like iTerm or Hyper or something else feel free to open that instead). We’re going to copy/paste the following install script from the Homebrew website:

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

🔥 Tip: When following tutorials, never copy/paste the dollar sign at the beginning of the line. They are generally used to resemble the prompt in your terminal and are just there to let you know that this is command is meant to be run in the terminal.

After Homebrew has been installed, we’re going to want to add the directory where Homebrew installs packages to our $PATH so our computer can find these new libraries and tools easily. In order to do this we’re going to want to run:

$ echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc

🔥 Tip: Whenever you make changes to any of your .bash* files (like we’re doing above), you either have to quit and relaunch Terminal OR source the .bash* file in order for the changes to take effect. If you want to source the .bashrc file, simply run $ source ~/.bashrc in your terminal.

At this point, running $ brew -v in your terminal should output the current Homebrew version info; if so, Homebrew (Brew) is working! Yay! 🎉
Another great little command worth running is $ brew doctor; this will perform a bunch of tests and then let you know if your computer has any issues with Brew at the current moment.

Getting PHP installed

Now that Brew is installed, we’re going to go ahead and install PHP. Now MacOS comes with its own version of PHP but often times it is quite out of date so we’re going to install the latest and greatest with Brew.

Craft CMS 2 will run on PHP 5.6, PHP 7.0, and PHP 7.1. I’d recommend installing PHP 7.1 unless you’re working on an older Craft site that might not support PHP 7 yet.

🔥 Tip: You can install multiple versions of PHP and switch between them as I described in-depth in another article. For the sake of this article, we’re going to install PHP 7.1, but the installation steps for each version follows the same basic pattern as below.

To install PHP 7.1, we need to run the following:

$ brew install php@7.1
$ brew services start php@7.1

It’s worth noting that the PHP formula recently underwent a name change, so even though most other articles on this subject still use the old formula names, the above lines of code are now the correct way to install PHP via Brew. Also, in the midst of the formula name changes, the greater majority of the PHP extensions got packaged up as part of the main formula, so you no longer have to install all the various extensions needed to make Craft work. There is one exception I found; that being the installation of the Imagemagick extension. Seems the correct way to install this now is something along the lines of this: (I haven’t been able to get it to work 100% perfectly yet but when I find a solution I’ll update this article)

$ brew install autoconf pkg-config imagemagick
$ export PHP_AUTOCONF=/usr/local/bin/autoconf
$ pecl install imagick
$ brew services restart php@7.1

Anyways, you should now have PHP 7.1 installed and setup to automatically start on login (which means you should never have to manually start or stop PHP yourself). You can check your current PHP version by running
$ php -v. Another helpful thing to verify is where your computer is getting PHP with $ which php— it should output /usr/local/bin/php.

🔥 Tip: A little more info on brew services — this is basically a handy little Brew command that interacts with the launchctl manager so you can setup certain “services” to automatically start when you login. To view a list of all the services you currently have setup, run $ brew services list. Services can be stopped, started, or restarted with $ brew services [stop, start, restart] *service* (optionally pass the --all flag instead of *service* to stop/start/restart all the services).

Composer for the win

Next, let’s install Composer. Composer is a nifty little tool that is used to manage PHP dependencies.

$ brew install composer

Let’s add Composer to our $PATH like we did with Homebrew (don’t forget to source your changes after as described above):

$ echo 'export PATH="$PATH:~/.composer/vendor/bin"' >> ~/.bashrc

Once that’s done, if you run $ composer -V you should see the Composer version outputted. If so, you’re on the right track!

Adding Valet to our setup

Alright, good job for making it this far! Next step is downloading Valet, which we will do via Composer:

$ composer global require laravel/valet

After that has finished running, if you run $ valet -V you should see Valet’s version outputted. Next we need to actually install Valet with:

$ valet install

And with that, you now have a local server up and running 🎉
If you $ ping valet.test from the command line it should return 127.0.0.1.

🔥 Tip: Simply running $ valet in the Terminal will output all the available Valet commands and a short description for each. I’ll mention the most important ones later on but figured it was worth noting here as well.

Managing the data

Now we should go ahead and get our database management system setup, whether it be MySQL or MariaDB or whatever else you prefer.

✏️ Note: MariaDB is a community-developed fork of MySQL that’s updated more often. MySQL is the default choice of most people but MariaDB is a great drop-in alternative to MySQL (in other words, databases created in MySQL work with MariaDB and vice versa).

MySQL

$ brew install mysql
$ brew services start mysql

MariaDB

$ brew install mariadb
$ brew services start mariadb

Craft in 3… 2… 1…

You can grab a zipped copy of Craft 2 from the Craft CMS website (click the “Download” button in the header and then click “Download Craft 2”). Unzip the downloaded file and move the extracted folder to a good location on your Mac (e.g. Sites or Projects or your home folder). Rename it to something memorable (we’ll need the folder name in a bit).

Plugging it all together

So here’s the magical part… We’re going to link the folder you downloaded in the previous step and set it up in Valet so we can view and work on the site in our browser.

You have one of two options to make this connection:

• You can connect to the folder containing the Craft files you downloaded.
• You can connect a parent directory with multiple subdirectories containing their own Craft files (think like a Sites or Projects folder setup).

Connecting just one site (aka `linking`)

This is pretty simple and should be used when you only want and need a connection to one site on Valet (or when you have multiple sites but they are in very different locations on your machine).

$ cd ~/path/to/craft-site
$ valet link

Your website is now available at craft-site.test!

For reference, your file structure should look something like this:

craft-site
    - craft
    - public
    - readme.txt

Connecting the parent directory (aka `parking` multiple sites)

If you are planning on working with multiple sites, it’s easier to just add the parent directory because any subdirectories will be automatically added to Valet with no extra commands!

$ cd ~/parent-directory
$ valet park

Now any subdirectories you create in parent-directory will be available at folder-name.test.

Your file structure in this case should look something like this:

parent-directory
    - app1
        - craft
        - public
        - readme.txt
    - app2
        - craft
        - public
        - readme.txt
    - app3                   <- (not a Craft site fwiw)
        - index.html
    - app4                   <- (also not a Craft site)
        - public
            - index.html

So now you will be able to visit app1.test, app2.test, app3.test, and app4.test in your browser and you will be served the file(s) from the respective folders.

🔥 Tip: A handy way to think of the difference in these connections is to imagine various types of garages. You might have a garage at your house for your car (similar to linking just one site). But in big cities you’ll often find parking garages, where you can park your car along with a bunch of others (similar to parking multiple sites in Valet).

Other helpful Valet tips:

• To use another local domain other than .test, run $ valet domain your-tld. For example, you could use .local or even .your-name.
• To generate a local SSL script for your site, navigate to the site’s directory and run $ valet secure. To revert back to plain HTTP, run $ valet unsecure.
• To share a local site with the rest of the world, navigate to the site’s directory and run $ valet share. Note: valet share currently does not work if a site is secured. First unsecure the site and then run $ valet share.

For more info on the ins and outs of Valet, I’d recommend checking out the Valet docs.

Config time

At this point you’re going to need to edit the Craft database config file (located at craft-site/craft/config/db.php) to use your local database credentials.

First, you will need to create a local database. If you’re familiar with the mysql cli, feel free to use that. Otherwise, I recommend using an app called Sequel Pro to connect to the local database management system we setup earlier and create a new database.

The credentials you should use to connect to your local database are the username root with an empty password and a database host of 127.0.0.1.

Success!

If all’s successful, you should be able to visit craft-site.test/admin in the browser and be welcomed by the Craft setup screen.

The Craft welcome screen

So to recap, we’ve now got Homebrew, PHP, Composer, Laravel Valet, and some form of a database management system installed and running. The process now for setting up a new Craft site is to download a copy of Craft, either link it via Valet or drop it in a currently parked folder, edit our database configuration, and then visit our site in the browser.

If you’re having problems with any of the above, please reach out to me and I’ll try to help you solve whatever issue you’re having. You can leave a comment below, ping me on Craft Slack (@jalen), or reach me on Twitter (@jalendport).

If you found this post helpful or enjoyed the read, please follow me here or on Twitter to see future posts!

Notes:

This article was written and tested with the following versions of software/tools:
macOS: 10.13.3
Homebrew: 1.5.14
Composer: 1.6.3
Laravel Valet: 2.0.10

Update 4/16/18: the Homebrew/php tap was recently deprecated and the php formula renamed and moved to core. This article has been updated accordingly.