SETTING UP A NEW MACBOOK PRO FOR LOCAL PHP DEVELOPMENT

Establishing a fresh development environment on a new machine might seem overwhelming, but it is a crucial step for ensuring a seamless workflow. This in-depth guide is designed to lead you through the steps of setting up your Macbook Pro (2019 edition) to actively support PHP and Drupal development. Starting with crucial security measures, the guide progresses to the installation of necessary tools and the configuration of virtualization, providing a comprehensive walkthrough for all the essential steps to kickstart your development journey.

The primary objective of this article is to offer developers a comprehensive guide for setting up and configuring all essential tools required for full-stack development. While some steps may cater specifically to Drupal development, these will be clearly indicated for the benefit of anyone interested.

• Essential Tools Installation

Developers will require the installation of specific tools, namely: Xcode, brew, git, curl, vim, and nvm.

Xcode is a package that provides crucial command-line tools for developers, such as git and gcc.

Homebrew acts as a package manager, streamlining and expediting the setup process. Using Homebrew facilitates the installation of other vital tools like vim (for file editing), git (for efficient version management), and curl (primarily for installation purposes).

bash

xcode-select –install
/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)”
brew install vim
brew install git
brew install curl

Every developer needs a text editor; hence, installing one is pivotal. Options like Atom and Sublime are viable, but this guide focuses on Visual Studio Code (VSC). A section at the end of the article will highlight some useful VSC extensions. Regarding terminals, choices include Hyper, iTerm2, or the standard terminal, but this guide opts for iTerm.

bash

brew install –cask iterm2
brew install –cask visual-studio-code

Once Visual Studio Code is installed, launch the application and press CMD+SHIFT+P. Search for “install code command in path” and select it. This action enables VSC usage through the terminal, aligning with the guide’s approach.

• Node Installation

For Node installation, utilize nvm. After installing nvm, follow the instructions provided by brew info to install Node.

bash

brew install nvm
brew info nvm
nvm install 12.11.1 # Preferred Node version

• Apache Setup

Begin using httpd from brew by first stopping and unloading apachectl with the following commands:

bash

sudo apachectl stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null

Subsequently, employ brew to install httpd. Post-installation, familiarize yourself with useful commands for starting, stopping, restarting, and accessing error logs.

bash

brew install httpd
brew services start httpd
brew services stop httpd
brew services restart httpd
tail -f /usr/local/var/log/httpd/error_log

By following these steps, developers can seamlessly set up their Macbook Pro (2019 edition) for efficient PHP and Drupal development, ensuring a smooth and productive workflow.

Upon completing the installation process, configuration of certain files is necessary, preferably using Visual Studio Code. If not, any text editor will suffice.

bash

code /usr/local/etc/httpd/httpd.conf

Locate the line stating “Listen 8080” and modify it to “Listen 80”.

Next, alter the “DocumentRoot” from “/usr/local/var/www” to “/Users/your_user/Sites” and make the same adjustment for the directory tag directly below it.

Change “AllowOverride” from “None” to “All” and uncomment “rewrite_module” to enable it.

Adjust the “User” and “Group” lines to prevent future permission issues. Substitute “User” with your_user and “Group” with staff.

Uncomment the “ServerName” line and set its value to localhost.

For the subsequent steps, create a Sites folder where all sites will be stored: mkdir ~/Sites. Then, create an index.html file to test the configuration:

bash

echo “<h1> Apache config works!</h1>” > ~/Sites/index.html

Restart httpd:

bash

brew services stop httpd
brew services start httpd

Tip: Double-check the user if issues persist.

• Database Setup

Utilize MariaDB (similar to MySQL) for the database:

bash

brew update
brew install mariadb
brew services start mariadb

After installation, modify the MySQL server password by running:

bash

sudo /usr/local/bin/mysql_secure_installation

It’s advisable to install an interface for interacting with databases. Choices include TablePlus or Sequel Pro; for instance, let’s use TablePlus:

bash

brew install –cask tableplus

OR

bash

brew install –cask sequel-pro

If Mac doesn’t trust any of these, go to system preferences > security and privacy, then click “Open Anyway” in the General pane.

Create a new connection with default settings, using the password set in the previous process (e.g., root).

To stop mariadb, execute:

bash

brew services stop MariaDB

• PHP Installation

As brew has deprecated certain PHP versions, utilize the tap from shivammathur for PHP installation:

bash

brew tap shivammathur/php

Install various PHP versions to switch between them:

bash

brew install shivammathur/php/php@7.1
brew install shivammathur/php/php@7.2
brew install shivammathur/php/php@7.3
brew install shivammathur/php/php@7.4
brew install shivammathur/php/php@8.0

It’s advisable to restart the terminal at this point for all configurations to update accordingly.

Now, let’s link the required PHP version. If a version is already installed, execute:

bash

brew unlink php && brew link –overwrite –force php@7.4

If not, run:

bash

brew link –overwrite –force php@7.4

During the linking process, two echo commands will appear. Copy and paste them. Subsequently, use php -v to verify the installed PHP version.

While PHP is installed, Apache needs configuration for PHP as well.

Open the httpd file once more:

bash

code /usr/local/etc/httpd/httpd.conf

Locate the ‘mod_rewrite’ module and append the following modules:

bash

#LoadModule php7_module /opt/homebrew/opt/php@7.1/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/php@7.2/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/php@7.3/lib/httpd/modules/libphp7.so
LoadModule php7_module /opt/homebrew/opt/php@7.4/lib/httpd/modules/libphp7.so
#LoadModule php_module /opt/homebrew/opt/php@8.0/lib/httpd/modules/libphp.so

Ensure only the module corresponding to the current PHP version remains uncommented—in this case, we’re using version 7.4.

As directory indexes currently cater only to HTML, update them to include PHP. Search for:

bash

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

Modify it to:

bash

<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Lastly, uncomment the deflate module line:

bash

LoadModule deflate_module lib/httpd/modules/mod_deflate.so

Restart httpd using brew. Now, to verify everything is set correctly, use the PHP function phpinfo(); to check the PHP version Apache is using. After executing the echo command, navigate to localhost/info.php to view the PHP version in use.

A useful script for switching between PHP versions, although optional, can save time if multiple PHP versions are required:

bash

curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw/adc8c149876bff14a33e3ac351588fdbe8172c07/sphp.sh > /opt/homebrew/bin/sphp

chmod +x /opt/homebrew/bin/sphp

Once downloaded, it’s straightforward to use. Simply run sphp followed by the desired PHP version. For instance:

bash

sphp 7.3

Lastly, perform a brew update and brew upgrade. If anything isn’t functioning correctly, it might necessitate an httpd restart.

6. Virtual Hosts

To configure virtual hosting in Apache, which allows testing multiple sites concurrently, we’ll utilize an existing Apache functionality called virtual hosting. This process will involve the use of Dnsmasq, a topic we’ll delve into shortly.

Start by editing the previously mentioned file:

bash

code /opt/homebrew/etc/httpd/httpd.conf

Uncomment the following lines:

bash

LoadModule vhost_alias_module lib/httpd/modules/mod_vhost_alias.so
# Virtual hosts
Include /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf

The final step is configuring the vhosts file:

bash

code /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf

In this file, Apache will be directed to locate various index files and the designated server alias. It’s advisable to comment out any previous configurations.

For Drupal configurations, it might be a bit complex. Here are examples for both Drupal and regular setups:

Drupal Configuration:

bash

<VirtualHost *:80>
    ServerName test
    ServerAlias *.test
    VirtualDocumentRoot /Users/your_user/Sites/site_directory/docroot
    ErrorLog “/private/var/log/apache2/site_directory.local-error_log”
    CustomLog “/private/var/log/apache2/site_directory.local-access_log” common
    <Directory “/Users/your_user/Sites/site_directory/docroot”>
        AllowOverride All
        Require all granted
        Options FollowSymLinks
    </Directory>
</VirtualHost>

Other Configuration:

bash

<VirtualHost *:80>
    DocumentRoot “/Users/your_user/Sites/your_folder”
    ServerName *.test
</VirtualHost>

Ensure the user used in the configuration file is consistent. Your_folder would represent the folder where the index files are stored.

Dnsmasq Configuration:

As previously mentioned, Dnsmasq facilitates dynamic host changes. For this guide, we’ll use “.test” as the domain.

Begin by installing Dnsmasq:

bash

brew install dnsmasq

Edit the configuration file:

bash

echo ‘address=/.test/127.0.0.1’ > /opt/homebrew/etc/dnsmasq.conf

Commence Dnsmasq and include it in the resolvers:

bash

sudo brew services start dnsmasq
sudo mkdir -v /etc/resolver
sudo bash -c ‘echo “nameserver 127.0.0.1” > /etc/resolver/test’

To verify if the setup is correct, attempt to ping any .test domain, such as test.test:

bash

ping test.test

A successful ping indicates the completion of your environment configuration!

8. Xdebug

Xdebug is an invaluable tool for debugging PHP code, especially when paired with Visual Studio Code, greatly enhancing web development. However, Xdebug isn’t universally standardized for PHP; its versions vary based on the PHP version. For PHP 7.1 and later, distinct Xdebug versions are available.

For PHP 7.1:

bash

sphp 7.1
pecl uninstall -r xdebug
pecl install xdebug-2.9.8

For PHP 7.2 and beyond:

bash

sphp 7.2
pecl uninstall -r xdebug
pecl install xdebug

Now, let’s configure Xdebug to ensure proper functionality. Initially, remove the zend_extension=”xdebug.so” line in the php.ini file. Although the example uses PHP version 7.4, the process remains consistent for all versions. Remember, if you switch versions later on, this step needs repetition.

Open the php.ini file:

bash

code /opt/homebrew/etc/php/7.4/php.ini

Create a new config file for Xdebug:

bash

code /opt/homebrew/etc/php/7.4/conf.d/ext-xdebug.ini

Paste the appropriate configuration based on the PHP version:

Prior to 7.2:

bash

[xdebug]
zend_extension=”xdebug.so”
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

After 7.2:

bash

[xdebug]
zend_extension=”xdebug.so”
xdebug.mode=debug
xdebug.start_with_request = yes
xdebug.client_port = 9003 #Depending on the VSC configuration
xdebug.idekey = VSCODE #Only needed if you are using VSC

Restart httpd and check the php.info page again; you should now find Xdebug in the correct version on the info page.

For finalizing the Visual Studio Code (VSC) configuration, head to the section dedicated to VSC setup, where all the necessary steps for configuring the application are detailed.

9. Key generation (ssh)

Creating SSH Keys:

If you’re planning to work with Git repositories or any other tool requiring SSH keys, follow these steps to generate a public and private key.

• Generate the key using ssh-keygen -t rsa. During the generation, it will prompt for a location; press Enter to use the default.
• For the passphrase, you can press Enter or type something depending on the level of security you desire. It’s common to leave it empty.
• The private key will be stored in the .ssh folder as id_rsa, while the public one will be named id_rsa.pub. Copy the public key using the command:

bash

pbcopy < ~/.ssh/id_rsa.pub

Custom Tweaks:

Visual Studio Code (VSC):

For VSC, there are some useful customizations and mandatory steps for Xdebug integration:

• Xdebug Setup:

• • Install the PHP Debug extension.
  • Go to the run and debug section in VSC and click on “generate a new launch.json.” Ensure the port matches the one configured in Xdebug.

Example launch.json:

json

{
    “version”: “0.2.0”,
    “configurations”: [
        {
            “name”: “Listen for XDebug”,
            “type”: “php”,
            “request”: “launch”,
            “port”: 9000
        }
    ]
}

• Allow Setting Breakpoints Everywhere:

• • • Go to Code > Preferences > Settings and search for “breakpoints.” Check “Allow setting breakpoints in any file.”

• Useful Extensions:

• • Beautify
  • Bracket Pair Colorizer
  • Drupal Syntax Highlighting (if using Drupal)
  • ESLint
  • Git History
  • GitLens
  • Highlight Matching Tag
  • Prettier – Code Formatter
  • Rainbow Brackets
  • Stylelint

Shell:

Use the following command to show hidden files in Finder and the terminal:

bash

defaults write com.apple.Finder AppleShowAllFiles true

Go to iTerm2 > Install Shell Integration.

These customizations and tweaks will enhance your development experience and streamline the use of specific tools like Git and Xdebug.

Conclusion

In conclusion, the process of setting up a development environment involves several intricate steps and configurations. From configuring tools like Xdebug for PHP debugging to generating SSH keys for secure access to repositories, each step plays a crucial role in facilitating a seamless development experience.

Additionally, customizing environments, such as Visual Studio Code, with specific extensions and settings tailored to individual needs significantly enhances productivity and coding efficiency. These adjustments, combined with shell integrations and tweaks, contribute to a more streamlined and efficient workflow.

The outlined procedures, whether in generating SSH keys, configuring Xdebug, or customizing development tools, aim to equip developers with the necessary resources and insights to optimize their development environments. Embracing these steps can lead to a smoother development journey, fostering better code management, debugging, and overall project execution.