The perfect Mac PHP setup.

April 12th 2021
|
Reading time 8 min

Are you starting out as a PHP developer on a Mac or does your environment cause frustration by not working properly from time to time? Then this article is for you. I'll show you what tools you need and why, and how to set them up. At the end of this article you have a fast development environment that is easy to extend, maintain and makes setting up new projects a breeze. Lets begin!

Understanding what we need

To install the right tools we first need to know what we're going to need. This seems obvious but knowing what you need helps you understand the tools we are going to install.

PHP compiler

In order to to run PHP code we need to be able to compile it. Compiling is just a fancy word for translating. A compiler translates the code you've written to something that the computer understands. So in order for your computer to understand PHP we will need a PHP compiler. From now on I will reference the PHP compiler just as PHP.

Webserver

After compiling the PHP code we want to view the result in the browser. This is where the webserver comes in. The webserver can receive requests and return responses which your browser can render in the form of a webpage.

Additional services

Besides displaying information you will most likely also want to store data, persistently and retrieve it at a later moment. This can be done with additional software like a database (MySQL or Redis for example). Which can be combined with PHP and a webserver to build whatever we want. Therefore having the ability to easily add and remove additional services is essential for a good development environment.

Package managers

As the amount of software has grown over the years managing it became a challenge. So package managers came to the rescue. There are specific package managers for each layer of software. We are going to install package managers for Mac OS, PHP, and Javascript.

Version control

To make setting up our web projects more easy as well as developing, extending, deploying and maintaining them, we will need a version control system. This keeps track of all the changes being made to the code and makes it all centrally accessible via services like GitHub.

Integrated Development Environment

To write code you can use a text editor. To make writing our code more easily we can use text editors that are like a Swiss army knife. We call them integrated development environments also known as an IDE.

Now we have a basic understanding what we need and why, we’re going to take a look at the specific services that can provide us with our needs.

The tools we're going to set up

In this section we are going to look at setting up the specific tools that will make our development environment complete, extendable and maintainable. The tools we are going to install are:

PHP - The PHP compiler

Valet - Preconfigured set of tools which also provides a webserver

Takeout - For installing and managing additional services

Homebrew - Package manager for Mac OS

Composer - Package manager for PHP packages

Yarn - Package manager for Javascript packages

Git - Version control system

Visual Studio Code - A powerful IDE for writing our code

To easily install the tools we will do it in a specific order as some services require other services to be installed first. Let start!

GIT

As mentioned earlier we will need a version control system to easily make use of other one's packages but also easily manage our own projects. Installing git on a Mac is done by installing the Command Line Tools. This doesn't just install git but also a very diverse unix toolkit which is essential for the work we're going to do in the command line. Lets do it:

  1. Launch the Terminal app on your mac (cmd+spacebar and enter "Terminal", it should show up)

  2. Type xcode-select --install and press enter

  3. In the popup window choose "Install"

  4. Wait for the installation to be completed

  5. When finished run git --version to confirm that you have git installed, output should be like "git version 2.24.3 (Apple Git-128)"

Curious what tools have been installed besides git? Open a finder window, in top menu click Go > Go to folder... > enter /Library/Developer/CommandLineTools/usr/bin/

Now we have git we can move to Homebrew

Homebrew

The applications that come with the command line tools are fixed, which means we can't easily add or remove additional command line tools we need. This is where Homebrew comes in. You can see it as an app store which is available in the command line. Under the hood it uses git which is why we needed to get that first. Alright, lets do it:

  1. In the terminal run the following command: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". Go through the installation steps and wait for it to be finished.

  2. After installation run brew doctor this should print "Your system is ready to brew".

Awesome the first package manager is installed! Let's proceed.

Links

PHP

By default your Mac comes preinstalled with PHP. However, this is an old version of PHP. To easily install a newer version of PHP and manage future versions, you've probably guessed it, we're going to use Homebrew. Lets do it:

  1. Open the terminal and run brew install php

  2. After the installation has been completed you can run php -v to verify it installed the latest version (at the time of writing its 8.0.3) If you see an older version you can run brew link [email protected] --force to let Homebrew switch forcefully. Still not working? Try rebooting your system.

Now that we have the latest version of PHP available to us we can proceed installing composer.

Links:

Homebrew installation instruction for PHP - https://formulae.brew.sh/formula/php

Composer

The second package manager we're going to install is Composer. This package manager is specifically focusing on easily installing and managing PHP based packages. Lets do it:

  1. Download composer. It's best to follow the instructions at https://getcomposer.org/download/

  2. You should now have composer.phar file in your current directory. Run ls in the command line to confirm its there.

  3. Next we want to make it globally available which means we can run the composer command from any directory in the terminal. Therefore we have to move the composer.phar file to the /usr/local/bin directory: run mv composer.phar /usr/local/bin/composer

  4. Run composer -V to confirm its available in the command line. You should see and output like "Composer version <version> <date and time>"

Now we have Composer installed its time to add Valet to our toolkit.

Links

Valet

We now have reached a critical point as we're going to install one the most essential tools in our toolchain, Valet. This is why Valet is so cool:

  • It installs the NGINX webserver, and makes sure it always runs in the background when your machine starts.

  • It lets you easily manage the active PHP version (it can even install other versions of PHP with the help of Homebrew)

  • It sets up DnsMasq which Valet uses to make your projects easily accessible locally via the .test TLD

  • Lets you secure your projects easily with a SSL certificate making your apps available via https

It basically does all the heavy lifting for us and it makes sure that what it manages just works. Lets install it:

  1. Open your terminal and run composer global require laravel/valet

  2. Run valet install

  3. After installation has been completed run ping foobar.test this should let the domain resolve to the default local IP 127.0.0.1 (press crtl+c to interrupt the pinging)

  4. Now navigate to the folder where your projects live. If you don't have a directory yet you can create a Sites directory in your home directory for example with mkdir ~/Sites . Enter the directory cd ~/Sites and run valet park

  5. Now any project you place in the Sites directory will be automatically picked up by Valet and makes it available under directory-name.test . That's just magic!

To secure your projects with a self-signed SSL certificate you can run valet secure <directory-name>. Now your project will be available at https://directory-name.test>. Now that we have Valet set up its time to proceed with Takeout

Links

Takeout

You now have the most important things set up and you can start developing your projects. However, you will reach a point where you want to work with additional tools like databases. You have many good options these days like TablePlus's DBngin. However, they are often limited to a certain set of tools. In the case of DBngin you are limited to database services. If that's all you're going to need its better to go with that and you can skip this part.

However, if you want easy access to more services like MeiliSearch, ElasticSearch or Expose. Takeout is a really good choice and it works well with Valet.

Under the hood Takeout uses Docker to install the specific containers for each service. A docker container is like tiny virtual machine that can run services in full isolation which makes the services more stable and less prone to misconfigurations. Did your service get corrupted? Just remove the container and reinstall it. With Takeout you can easily manage this.

First we need to install Docker:

  1. Go to https://www.docker.com/get-started and download the installer

  2. Run the installer

  3. After installation open your terminal and run docker -v this should show an output like "Docker version 20.10.5, build 55c4c88".

Lets install Takeout

  1. Open the terminal and run composer global require tightenco/takeout

  2. Add ~/.composer/vendor/bin to your systems system's "PATH" in order to make the Taketout command available in your terminal:

    1. In your terminal enter cd ~

    2. Run ls -la and see if there is a .zshrc file. If there is none can create it manually with touch ~/.zshrc .

    3. Run echo export=$HOME/.composer/vendor/bin >> ~/.zshrc

    4. Run source ~/.zshrc to reload the environment

    5. Now the commands of globally installed composer packages are available via the command line

  3. Run takeout to see if it's available. You should see its version and available commands

  4. You can enable specific service by running takeout enable and by hitting the space bar you can select a service. Takeout will take care of the installation and running it.

Good to know: As Takeout depends on Docker, Docker needs to be running in order to use Takeout. After each system reboot you'll have to manually start all enabled services. You can easily do this via the command line with takeout start --all

Links

Yarn

To easily manage our Javascript packages for each project we are going to look at the final package manager we'll need, Yarn. Besides managing packages a tool like Yarn is also essential for modern web development that lets you run scripts the can run dev servers or compile assets for production.

Instead of Yarn you can also go with NPM. There has been quite a debate which one is better but they are nowadays so close when it comes to speed and features that it doesn't really matter which one you use. I personally like Yarn more as it seems faster and has a nicer output compared to NPM.

  1. First we need to install Node which allow use to run command line programs like npm and yarn. Open your terminal and run brew install node

  2. After installation run node -v to see if node installed successfully, at the time of writing the latest version is v15.14.0

  3. Now that we have Node installed you already have access to NPM. So if you're good with NPM you can leave it at this. If you'd like to install Yarn, continue

  4. In your terminal run npm install --global yarn

  5. Run yarn --version to see if Yarn has been installed successfully. This command should output the version number like 1.22.10

With Yarn installed its time to complete our perfect setup with a good IDE, VS Code.

Links

Visual Studio Code

There are many different IDE's but for me the preferred IDE is VS Code. It's a very mature IDE with a ton of extensions available and its completely free. There are also other popular options like JetBrain's PhpStorm. I personally dislike PhpStorm as it feels really bloated, it got really slow at one point for me, has no better or real unique significant features compared to VS Code and its a paid product (this isn't a bad thing but it needs to be 10x better than VS Code for me to consider it, which it isn't).

To install VS Code head to https://code.visualstudio.com

Whats next

We finished setting up our modern hassle-free PHP development environment for a Mac. In the next article we will take a look at extending our development environment with additional services, packages and tools. In the final part of this blog series we will take a look at how we can maintain our environment. We'll look at updating, upgrading and troubleshooting. To not miss these articles make sure to follow me on Twitter or sign up to my newsletter.

👋
Lets connect

If there is anything unclear in this article or do have any feedback to improve it, always feel free to reach out to me on Twitter or email.