Setting a Mac for Web Development

These notes were update for 10.15 (Catalina)

Install brew

I use Brew to install libraries and software.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

XCode Command Line Developer Tools

Installing brew will do this for you, but just in case.

xcode-select --install

Accept the XCode licensing

sudo xcodebuild -license

Apache Web Server

Some important paths and executables to manage Apache in MacOS are:

Path/Command	Description
/etc/apache2/	Apache directory
/etc/apache2/httpd.conf	httpd.conf
/usr/sbin/apachectl	Apache Control executable
sudo apachectl start	Start apache
sudo apachectl stop	Stop apache
sudo apachectl restart	Restart apache

Configure Apache

We need to edit our httpd.conf:

sudo nano -w /etc/apache2/httpd.conf

In the httpd.conf we mainly find and uncomment (remove the initial # ) of a configuration line to enable a feature.

Some basic functionality that you should uncomment are:

LoadModule include_module libexec/apache2/mod_include.so
LoadModule alias_module libexec/apache2/mod_alias.so
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
LoadModule userdir_module libexec/apache2/mod_userdir.so
LoadModule userdir_module libexec/apache2/mod_userdir.so

Uncomment this line to enable user home folders.

Include /private/etc/apache2/extra/httpd-userdir.conf

To enable PHP uncomment this line:

LoadModule php7_module libexec/apache2/libphp7.so

We change the DocumentRoot to point to your user's sites folder, by changing the path from "/Library/WebServer/Documents" to "/Users/ctk/Sites". Search the httpd.conf and replace the path in these two lines:

Before	After
DocumentRoot "/Library/WebServer/Documents"	DocumentRoot "/Users/ctk/Sites"
<Directory "/Library/WebServer/Documents">	<Directory "/Users/ctk/Sites">

In my case the username is ctk, change the line with your username. ( Run the command whoaim if you need to find which one is your username. )

In your <Directory "/Users/ctk/Sites"> directive we have to make some more changes.

To enable ".htaccess" files set AllowOverride from None to All.

Enable rewrite logging:

LogLevel debug rewrite:trace8

Create a config file for your username.conf. For example my username is ctk so my configuration file will be: /private/etc/apache2/users/ctk.conf`.

Edit the file: nano -w /private/etc/apache2/users/ctk.conf

Add the following configuration options to your user conf file:

<Directory "/Users/ctk/Sites/">
AllowOverride All
Options Indexes MultiViews FollowSymLinks
Require host localhost
</Directory>

Save the conf file and change its permissions:

sudo chmod 644 /private/etc/apache2/users/ctk.conf

When you do changes to your http.conf you need to restart apache:

sudo apachectl restart

If you are going to use the default Document Root you may need to change its permissions to allow your user to easily manage the folder:

sudo chgrp -R staff /Library/WebServer/Documents
sudo chmod g+rws /Library/WebServer/Documents
sudo chmod -R g+rw /Library/WebServer/Documents/

Enable PHP

OS X, 10.10 Yosemite comes with PHP 5.5.14 ready to use.

To enable PHP edit your httpd.conf

sudo nano -w /etc/apache2/httpd.conf

remove the # from the this line:

LoadModule php7_module libexec/apache2/libphp7.so

Prepare php.ini:

sudo touch /etc/php.ini
sudo chmod ug+w /etc/php.ini
sudo chgrp admin /etc/php.ini

Basic php.ini:

[PHP]

date.timezone = "America/Puerto_Rico"
error_reporting  =  E_ALL
display_errors = On
log_errors = On
include_path = ".:/usr/local/lib/php/pear"

[xdebug]
zend_extension=/usr/local/php/extensions/xdebug.so
xdebug.remote_enable=on
xdebug.remote_log="/var/log/xdebug.log"
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

Debugging PHP

Enableling XDEBUG under Catalina gets confusing because online discussions are not clear, there are two scenarios: You are using the default PHP instalation or you have a homebrew install.

NOTE: If you attempt to download and compile xdebug you will get many errors, mainly because in MacOS Catalina the traditional /usr/library/ is placed inside the SDK. Traditional linux tools will not be able to compile.

References Removed /usr/include, xDebug in Catalina.

HINT: When working with more traditional makes add this: export CPATH=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include The actual path for the SDK can be found by running xcrun --show-sdk-path.

In BigSur you have to use Homebrew.

Enable xdebug in Catalina using the default install of PHP.

Copy the xdebug extension to your own folder

sudo mkdir -p /usr/local/php/extensions
sudo cp /usr/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so /usr/local/php/extensions

Edit "/etc/php.ini" and add the following lines:

[xdebug]
zend_extension=/usr/local/php/extensions/xdebug.so
xdebug.remote_enable=on
xdebug.remote_log="/var/log/xdebug.log"
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

Using MACGDBP with xdebug for local debugging:

Download MACGDBP from https://www.bluestatic.org/software/macgdbp/

Add these lines at the end of your /etc/php.ini".

[xdebug]
xdebug.var_display_max_children = 999
xdebug.var_display_max_data = 999
xdebug.var_display_max_depth = 100

xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1

Restart apache

sudo apachectl restart

Basic use of XDEBUG and MACGDBP

Open MACGDBP.

When dubiging a php script add the "XDEBUG_SESSION_START=1" to your url for example:

http://localhost/test.php?a=test&XDEBUG_SESSION_START=1

Your script will pause/wait, you are now on the debugger, switch to MACGDBP and step thru your code or hit "continue".

To stop debugging use the "XDEBUG_SESSION_STOP=1" parameter in your url.

To set a breakpoint use the "xdebug_break()" function in your php script. For example:

<?php

print "here<br>";
doThis("jose cuevas");

function doThis($n){
  xdebug_break();
  print 'Hello ' . $n . '<br>';
}
?>

If you set add xdebug.start_with_request=trigger to your ini then you can use xdebug_break() without using XDEBUG_SESSION_START and XDEBUG_SESSION_STOP.

To automatically break into MACGDBP when an exception is thrown set the "remote_mode" to "jit".

<?php 
ini_set('xdebug.remote_mode', 'jit');

?>

PEAR and PECL

To enable PEAR you first have to install autoconf. If you get errors with brew see the "fix brew" section.

brew install autoconf

Install pear

cd /tmp
curl -s -O https://pear.php.net/install-pear-nozlib.phar
sudo php install-pear-nozlib.phar -d /usr/local/lib/php -b /usr/local/bin

Upgrade your PEAR installation:

sudo pear channel-update pear.php.net
sudo pecl channel-update pecl.php.net
sudo pear upgrade-all

You php.ini should have the following path (include_path):

include_path = ".:/usr/local/lib/php/pear"

Installing MySQL

Visit http://dev.mysql.com/downloads/mysql/ and download the "Mac OS X 10.9 (x86, 64-bit), DMG Archive".

Change the MySQL root password:

mysqladmin -u root password {new-password}
mysqladmin -u root -p{new-password} -h localhost password {new-password}
mysqladmin -u root -p{new-password} reload

If paranoid clear your history:

history -c

Installing PHP SSH2 Extension

Info at http://php.net/manual/en/book.ssh2.php

brew install libssh2
sudo pecl install ssh2

Add the extension to your "php.ini".

extension="ssh2.so"

Other hints and resources

Brew

See what you have installed

brew list

Fix brew

If you are upgrading a Mac to a new OS your brew installation may need to be fixed:

rm -rf /usr/local/Cellar /usr/local/.git && brew cleanup
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

or edit your brew.rb and change the first line from “1.8″ to “current”

sudo sh
nano /usr/local/Library/brew.rb

it should read like this:

#!/System/Library/Frameworks/Ruby.framework/Versions/Current/usr/bin/ruby -W0

fswatch

fswatch is a file change monitor that receives notifications when the contents of the specified files or directories are modified.

brew install fswatch

Watch a folder and run a script

fswatch -o ~/path/to/watch | xargs -n1 ~/script/to/run/when/files/change.sh

Monitor a path and execute a script only once

fswatch -1x --event Created --event Updated --event Removed --event Renamed --event MovedTo ~/Desktop/fsw | xargs -0 php t.php

Locale errors

The terminal app my try to set the locale for each ssh connection, in some instances giving the error "warning: setlocale: LC_CTYPE: cannot change locale (UTF-8): No such file or directory Fix".

To fix this go to the terminal app preferences in "Profiles", select the profile used and go to the "Advanced" and uncheck the "Set locale environment variables on startup".

Check this link for a good discussion on this topic.

ctkjose/macoswebdev.md