Setup PHP Dev Environment on Mac OS X Sierra – Apache, MySQL & PHPMyAdmin

Getting the development environment right at the start is vitally important to productive application development. Here we will setup a flexible “LAMP” development environment on the latest Mac Os X, El Capitan. We will focus on keeping the development platform flexible and stable, centrally managing all system & application dependencies. Within a few minutes, we will hopefully have advanced PHP web applications serving up pages, but with the ability to integrate extra system components specific to your application.

System (optional)

Apple’s native development IDE is XCode, it’s not great for PHP but provides handy tools and installing it kind of tells Apple your computer’s being used for software development and to unlock related features. If you’re starting on a completely fresh system, it’s a good idea to install Apple’s Xcode tools. Open up the Terminal App, e.g. cmd + space then: terminal  and type:

sudo xcode-select --install
sudo xcodebuild -license

You will have to agree to some terms & conditions but prevents later problems using common tools like Git.

Install Apache and PHP7 (or other versions)

Install the amazing and free open-source Homebrew  package management system which will make open-source software development far more manageable. If you’re not yet convinced by Homebrew, check out its popularity on GitHub. Install Homebrew as such:

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

As of writing, the most recent version of PHP is 7.0, although Mac already has PHP and Apache inbuilt, we will install it using Homebrew to better manage all development services & dependencies – they’ll be all in one place, managed using a standard set of commands. Allowing us to easily upgrade & downgrade PHP, also since Apache (the web server / engine) keeps changing between MacOS releases, we will use Homebrew to manage and keep it consistent.

Fist stop the default Apache service, in the terminal type:

 sudo apachectl stop
 sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null
 brew install httpd24 --with-privileged-ports
 brew install php71
[short wait to download files]
 brew services start homebrew/apache/httpd24

This should take a minute or less and Homebrew is usually really good at providing helpful and clean output info, errors and ways to fix them. For example, it may give you info about where the php.ini file is, (e.g. /usr/local/etc/php/7.0/php.ini ) or suggest the following command to automatically start PHP7 at login:

 brew services start homebrew/php/php70

As mentioned, helpful and clean output info is one of Homebrew’s real strong points, always read what it outputs!

Verify PHP7 installation (optional)

These are a few really useful commands to check everything is working, or diagnose any problems:

Format:   command
                     output

    php -v

PHP 7.0.8 (cli) (built: Jun 23 2016 16:32:40) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies

    which php
/usr/local/bin/php

    ls -l /usr/local/bin/php
lrwxr-xr-x  1 maltronic  admin  36 30 Aug 19:20 /usr/local/bin/php -> /usr/local/Cellar/php70/7.0.8/bin/php

     php -i | grep php.ini
Configuration File (php.ini) Path => /usr/local/etc/php/7.0
Loaded Configuration File => /usr/local/etc/php/7.0/php.ini

If for any reason there’s a problem you can manually point php to the desired version. First, check what Kegs are have installed in your Cellar using:

brew list

If no version of php appears, try “tapping” homebrew to enable it to pick up more software kegs then installing php7 like so:

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php
brew install php70

You can link to whichever installed PHP version you like, say you wanted to use PHP 5.6 (and have installed it using brew install php56 then create a symbolic link to /usr/local/bin/php:

ln -s /usr/local/Cellar/php56/5.6.23/bin/php /usr/local/bin/php

Enable Debugging (optional)

Stop haphazardly print variables to the screen and become a real pro developer, use debugging! It’s so easy and better for fixing bugs. To install Xdebug and enable IDE debugging using popular IDEs like Netbeans and PHPStorm, install with homebrew:

brew install php70-xdebug

Install MySQL

Although MariaDB is slowly replacing MySQL in open source circles, either can be installed, as such:

brew install mysql

Just replace “mysql” with “mariadb” (for rest of article). The Homebrew MySQL/MariaDB server should now be running, this can be verified with:

brew services list

Typing just brew services lists the Homebrew’s service manager commands. If mysql isn’t already running, type brew services start mysql

Configure Apache

We will keep on using the preinstalled Apache server but edit the Apache config file to enable the PHP7 module. Use Mac’s inbuilt nano editor or another text editor (like Sublime Text):

sudo nano /etc/apache2/httpd.conf

Add the following line:

  LoadModule php7_module /usr/local/opt/php70/libexec/apache2/libphp7.so

Press ctrl + x to quit.

Now, every site we add will be a new VirtualHost in Apache, one of potentially many web applications running on your computer. Whilst you can edit the /etc/hosts file to enable local domain names, a quick and reliable technique is to use different ports to distinguish websites. First, make sure Apache is checking for Virtual Hosts and that there’s no # commenting out the file:

sudo nano /etc/apache2/httpd.conf

Go right to the bottom of the file (ctrl + v is PAGE DOWN) and ensure the following line does not have a # infront, it should look like the middle line below:

...

Include /private/etc/apache2/other/*.conf

...
(i.e. no #, although the * is ok)


Now edit Apache’s VirtualHost config file, using the nano editor command:

sudo nano /etc/apache2/extra/httpd-vhosts.conf

And add a VirtualHost config for your website:

Listen 81

DocumentRoot "/Users/maltronic/my_php_project/web"
ServerName "local.my_php_project"
ErrorLog "/var/log/apache2/my_php_project-error.log"



Options Indexes FollowSymLinks
AllowOverride All
Require all granted

Where the directory (“web” above) is the base directory that will appear on your website (i.e. where index.php or an equivalent would sit).

Now, finally, we restart the Apache server to apply our changes:

sudo apachectl restart

Some errors may appear (especially in regards to domain names), these generally don’t matter although if there’s an obvious problem stated you should fix it and re-run the restart command.

Install PHPMyAdmin

As usual, install PHPMyAdmin using Homebrew:

brew install phpmyadmin

And as usual, Homebrew will give some info on any final steps, which in my case means:

sudo nano /etc/apache2/httpd.conf

Then adding to the bottom of the file (ctrl + v is page down in nano):

Alias /phpmyadmin /usr/local/share/phpmyadmin

Options Indexes FollowSymLinks MultiViews
AllowOverride All

Require all granted


Order allow,deny
Allow from all

Install Composer (optional)

Composer is a near universally adopted PHP package manager that enables your PHP applications to use 3rd party libraries and manage their dependencies (very similar to Homebrew but for your PHP application (on any OS), rather than Mac Operating System).

It’s not needed yet, but most professional and open-source projects use it. For consistency let’s install it using Homebrew:

brew install composer

As usual, look at the screen output for any errors and info.

That’s It

Try loading PHPMyAdmin in a web browser at:

http://localhost/phpmyadmin

By default the MySQL admin user is: root (with no password).

You now have a fully functioning and extremely flexible LAMP development environment. From here you can easily add additional services like Redis, Memcache, RabbitMQ, other databases and whatever else you would like to use in your project


This guide gets updated based on reader comments. Any problems, please comment below or share on social media if you found this guide useful!

Advertisements

Make mysql databases default to UTF8

By default MySQL databases are created with one of the latin charsets – as if globalization never happened – and just asking for future internationalization and charset issues. UTF8 is the generally accepted way forward (for now) and there are few occasions that it isn’t the best charset to use.

Ideally, some sort of framework config system will take care of this but otherwise for existing MySQL databases, you can find out their current charset by entering the MySQL terminal and typing:

SELECT default_character_set_name FROM information_schema.SCHEMATA WHERE schema_name = "myDatabase";

The problem is changing the character set of an in-use databases can be troublesome and you have to remember to specify UTF8 as the charset every time you create a new database. Also many database tools (e.g. PHP’s Doctrine) do not currently support creating a database with a non-default charset.

The best solution is to set the default charset to UTF8 straight after installing mysql and avoid the problems before the occur. This can be done simply by modifying /etc/mysql/my.cnf (note my.conf may be located elsewhere) and adding the following lines to the [mysqld] section:

collation-server = utf8_general_ci
character-set-server = utf8

Then restart the MySQL service:

sudo service mysql restart

Now new databases will now be created using the UTF8 character by default.

Stopping favicon 404 spam in Apache error logs

Favicons display many elements of the dark, early days of the Internet. Typically a 16×16 pixel image in ICO format (wtf is that?), they were introduced back in 1999 with Internet Explorer 5. More recently mobile browsers have followed in this unholy tradition by introducing more favicon files, bringing the list of files needing to be created / handled to:

  • favicon.ico
  • apple-touch-icon-precomposed.png
  • apple-touch-icon.png

Whilst they do provide a nice little visual logo space for your website or company, you may sometimes think they aren’t worth the bother. One unexpected problem: An Apache error log full of 404 errors from web browsers trying to locate /favicon.ico, /apple-touch-icon-precomposed.png and /apple-touch-icon.png files in your website’s root directory.

A simple way to prevent this is to add the following code to your apache virtualhost configuration:

Redirect 404 /favicon.ico

<Location /favicon.ico>
    ErrorDocument 404 "favicon does not exist"
</Location>

Redirect 404 /apple-touch-icon-precomposed.png

<Location /apple-touch-icon-precomposed.png>
    ErrorDocument 404 "apple-touch-icon-precomposed does not exist"
</Location>

Redirect 404 /apple-touch-icon.png

<Location /apple-touch-icon.png>
    ErrorDocument 404 "apple-touch-icon does not exist"
</Location>

Whilst this solution seems the most technically correct, it still means your server is going to be hit with constant 404 requests for the non-existant files on every page and frame load, although thankfully they should no longer be clogging up error logs. A more pragmatic approach is to create 3 blank files, 1 in ICO format and 2 in PNG format, placing them in your website’s root public directory as favicon.ico, apple-touch-icon-precomposed.png and apple-touch-icon.png. A good tip is to set the Expires header to sometime in the distant future to avoid any further favicon requests.

You will also need to add the following code to your page:

<link rel="shortcut icon" href="#" />

Now finally you can live in peace from bombardment of favicon requests …until browser makers start adding new favicon types.

libssh2 vs phpseclib

As tempting as it can be to make use of the simple include library which is phpseclib, it is better (if possible) to install the libssh2 module. Libssh2 it grants PHP access to your system’s OpenSSL implementation rather than relying on phpseclib’s own version which is reason alone to use libssh2 despite phpseclib being undeniably more portable, faster and offering enhanced debug facilities (there’s nothing to stop you switching to phpseclib purely to debug pesky issues or writing code first in phpseclib then porting to libssh2).

Whilst OpenSSL has come under attack recently with exploits such as Heartbleed, it remains one of the best tested and trusted security suites around. Major exploit discoveries like Heartbleed and Shellshock (with its openSSH attack vector) demonstrate the need for systems to be patched as soon as possible.

By using libssh2, any patch to the system’s OpenSSL implementation will be automatically applied to your PHP applications. On a related note, unattended-upgrades / yum-cron should always be enabled to ensure you are patched against exploits as they are released with a seemingly increasing regularity.

On a Ubuntu / Debian libssh2 can be installed via the command:

sudo apt-get install libssh2-php

On Red Hat based systems, use:

yum install libssh2

You then need to add the module to your php.ini file with the following line (place it after all the other extension loading calls):

extension=ssh2.so

Then finally restart apache.