Getting Started with Craft CMS 3 and Laravel Valet

10 min readFeb 23, 2018

Using Craft CMS 2? Check out my **Craft 2 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.

🔥 Tip: If you’re more of a visual learner, I highly recommend Ryan Irelan’s videos on Craft. The ones particularly relevant to this article are Installing Composer on macOS and then Installing Craft 3. He’s also got some great courses over at mijingo.com if you’re interested in learning more about Craft.

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 3 will run on PHP 7.0+. 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

Setting up the directory

Let’s create a folder for our Craft 3 project:

$ mkdir ~/path/to/craft3-site

Now we’re going to link that folder to our Valet server so we can view and work on the site in our browser.

You have one of two options to make this connection:
1. You can connect to the folder containing the Craft files you downloaded
2. 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/craft3-site
$ valet link

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

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

craft3-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
        - templates
        - vendor
        - web
        - README.md
    - app2
        - templates
        - vendor
        - web
        - README.md
    - 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 run $ valet secure your-site-name. To revert back to plain HTTP, run $ valet unsecure your-site-name.
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.

Craft in 3… 2… 1…

Let’s download and install Craft 3 into the folder we created in the last step. With the release of the Craft 3 GA, you can now download Craft 3 as a zipped folder from the Craft website like you could do for Craft 2 (click the “Download” button in the header and then click “Download Craft 3”).

However, the recommended method of downloading is via Composer, so we’ll use that for this article. If you’re downloading a zip from the site, you can continue to the next step; otherwise, please run the following to get the latest Craft files:

$ composer create-project craftcms/craft ~/path/to/craft3-site

What exactly is that command doing?

composer create-project → pretty straightforward, we’re telling Composer to create a project
craftcms/craft → for this new Composer project, we want to use the official craftcms package
. → and we want it downloaded in the current directory

When Composer is done downloading Craft 3, you should see this nice Star Wars looking splash screen in your Terminal:

Config time

Now it’s time to actually install & setup Craft.

There are currently two different ways to do this. We can either:

Edit our .env file and then visit our site locally in the browser to complete the setup (similar to how one would setup Craft 2) OR
Run a provided installer script that does it all for us.

Edit the `.env`

So, if you look in the directory where Composer just downloaded Craft 3, you’ll find a .env file where we can set some environment specific settings. If you’re not seeing this file, it’s possible you have dot files hidden.

Open up the .env file and go ahead and edit the settings found there (specifically the database-related ones) to reflect your local setup.

Then visit craft3-site.test/admin and you should see the Craft install screen:

Follow the directions and you should have your Craft site running in no time.

Run the provided installer script

Alternatively, we can take advantage of a little installer script that the great folks at Pixel&Tonic thoughtfully included with their Craft package. If you note, under the “Star Wars” splash screen mentioned a couple steps back there is a little snippet that reads something along the lines of:

Welcome to Craft CMS! Run the following command if you want to setup Craft from your terminal:~/Sites/craft3/craft setup

Go ahead and run that script they provided you with. Follow the prompts to input your database & site information:

After you’re done providing your info it should take under 5 seconds to install Craft and setup the site for you. So much faster than the browser method, eh?

Success!

If all’s successful, you should be able to visit craft3-site.test in the browser and be welcomed by the Craft default index template.

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 via Composer, either link it via Valet or drop it in a currently parked folder, edit the env file or run the provided script, 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.