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.
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
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.
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
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.
- 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!
- 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.
- 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:
-
- 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.”
-
- 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.