1. Install ImageMagick

sudo port install ImageMagick

2. Install imagic module

You’d expect to just be able to run “pecl install imagick” and I would probably try it first.  However the instructions below will work if the automatic installation returns the error: ImageMagick MagickWand API configuration program… configure: error: not found. Please provide a path to MagickWand-config or Wand-config program. ERROR: ‘/private/tmp/pear/temp/imagick/configure –with-imagick=/opt/local/bin/’ failed.

Note version is 3.0.1 in these instructions, adjust the commands depending on the version that is downloaded by pecl.

pecl download imagick
tar xvzf imagick-3.0.1.tgz
cd imagick-3.0.1
phpize
./configure --with-imagick=/opt/local
make
sudo make install

The install process will create a file “imagick.so”, but it may not be automatically installed in the correct location depending on your PHP path settings.  The install will output the location of the .so file so if necessary, you can manually move that file to the extensions directory for your web server.

3. Append to php.ini

extension=imagick.so

That should be it.  Restart Apache and view phpinfo.php. There should be a section for ImageMagick

Most of these errors I feel are due to developer fear and paranoia that the end user will see an error message. Nobody wants their customer to encounter bugs and errors, but there is a difference between an app that is solid and one that simply hides problems. It’s much harder to fix a bug that nobody knows is there. I’ve written about this before in my article about insidious bugs.

1. Sticking Your Head in the Sand:

try {
  // ... code here...
} catch (e) {
  // hope this never happens!
}

A try/catch statement with no error handling inside the catch statement is a great way to mask errors. (masking errors is bad!) Your code quietly suppresses the error and no user or developer will see a problem unless they notice unusual behavior of the app or data loss. This seems to be a strategy used when the code contains an expected error that can be safely ignored and shouldn’t halt the program. That is a dubious assumption but assuming it is true, the danger with this strategy is that a different, unexpected error might also occur. Because this try/catch doesn’t discriminate it will mask all errors that occur and will hide a situation that wasn’t anticipated.

A better approach (assuming the exception that can be safely ignored) might be to first ensure the try/catch surrounds only the most minimal code or line in question. Then when the error is caught, verify that this is the expected exception and not something else by checking the exception type, id, etc (depending on the language). It can be helpful to at least write a “warning” to the console or a log file so that when another developer is trying to fix your bugs, he/she will have some clues as to what your logic was when you were writing this code.

2. Attempting to Set Things Right:

try {
  i = x.toUpperCase();
} catch (e) {
  // x must be null.  wonder why...?  oh well, let's fix it!
  i = "";
}

Handling an exception by ignoring faulty input and setting variables to arbitrary, default values can be dangerous. This has a high probability of creating “insidious” bugs because they don’t always address the cause of the exception and simply try to fix it. Again, this masks problems and makes apps extremely difficult to debug.

The optimal way to handle this scenario is to prevent the invalid input at it’s source, before it gets passed into a method or function. If this method is supposed to gracefully handle bad input then it should do so by checking for legitimate values explicitly instead before using them. If the input doesn’t validate then throw an exception. This is a scary concept to novice and sloppy programmers alike because they are afraid of creating errors that must then be hunted down and fixed at the source. However what this really does is to *reveal* bugs in faulty calling code. Revealing bugs is a good thing. It can, unfortunately, open a can of worms and a lot of sloppy calling code now becomes your problem!

3. The Hot Potato:

try {
  // ... code here...
} catch (e) {
  // whew!  good thing we caught this!
  throw e;
}

A useless try/catch that simply re-throws the original exception does nothing to improve the code. This is probably the least harmful mistake because it doesn’t mask errors. However the code is worthless and does nothing to help with debugging or make the app more stable.

The solution is to just remove the try/catch and let the original error occur. The end result is the same.

4. Re-branding Exceptions:

try {
  // ... code here...
} catch (e) {
  // jason said throwing exceptions is good. i wonder what he meant?
  throw new Exception( e.getMessage() );
}

Catching an exception and then throwing a new exception with some of the original info. This example may not mask bugs but it can make the original problem difficult to locate. The stack trace of the original exception probably contains clues about the original source of the error, but you lose all of that information when you create and throw a new exception.

Believe it or not, a good way to handle this is to remove the try/catch. There is one legit reason (in my opinion) to throw a new exception. If you anticipate an exception to occur and 1) you are able to keep the application in a known state and 2) you need the error text to be more friendly or understandable. For example, if you expect a network connection exception to be thrown under normal conditions then you may want to create your own exception that says “Network Unavailable” instead of a allowing a cryptic error message to come from a low-level network API. However you do need to be meticulous and add logic to verify that you are catching only the expected exception and not something else. Because if you are expecting a network exception but instead get an “index out of bounds” then your “Network Unavailable” message is not only masking a bug, but potentially sending another developer on a wild goose chase.

Those are the situations that I was able to think of off the top of my head. Do you have any other try/catch situations worth mentioning? Feel free to leave them in the comments.

1.Turn on Apache

Go to System Settings->Sharing and turn on Web Sharing. If necessary click the button that says “Create Home Folder” which will create a folder called “Sites” in your home directory.  You now have a web server that you can access at http://localhost/~username/  (“username” being your own account login name)

2. Edit /private/etc/apache2/httpd.conf

To enable PHP uncomment (remove the number sign at the beginning of) the line:

#LoadModule php5_module libexec/apache2/libphp5.so

(optional) you can re-map the server root to your home website directory by editing DocumentRoot:

DocumentRoot “/Users/username/Sites”

If you wish to use .htaccess files then look a bit further down AllowOverride and set it to “All” like so:

Options FollowSymLinks
AllowOverride All
Order deny,allow
Deny from all

3. Edit /private/etc/apache2/users/username.conf

Your user directory has it’s own permissions as well which are located in this separate file.  You may wish to enable FollowSymLinks and AllowOverride again here by changing these two lines like so:

Options Indexes MultiViews FollowSymLinks
AllowOverride to All

4. Copy /private/etc/php.ini.default to /private/etc/php.ini

OSX includes a default php.ini file that you can use but you must rename or copy it first.  If you don’t do this then PHP will still run but it will just be using the default initialization settings with no way for you to override them.

Edit these settings in php.ini (some of these settings will not come into play until they are installed)

display_errors = On
mysql.default_socket = /tmp/mysql.sock
pdo_mysql.default_socket=/tmp/mysql.sock
date.timezone = ‘America/Chicago’
include_path = “.:/usr/lib/php/pear”

5. (Optional) Install PEAR

If you use the PEAR libraries you can install them using the included phar file like so:

sudo php /usr/lib/php/install-pear-nozlib.phar
sudo pear config-set php_ini /private/etc/php.ini
sudo pecl config-set php_ini /private/etc/php.ini
sudo pear upgrade-all

6.  Install MySQL

This doesn’t really require instructions, simply download the latest MySQL from mysql.com.  I installed the 32 bit version, however it may be possible to run the 64 bit version as well.

7. (Optional) Install Apache Plugins

If you use encryption you may need to install mcrypt.  Instructions have been provided by Michael Gracie

If you use the Zend debugger you can install that using these instructions.

Using a debugger really pays off in the long run in my opinion.  It gives you so much visibility and insight into what’s happening in your code and allows you to work faster.  Most developers that I know don’t bother installing a debugger for PHP web applications because either they either aren’t aware of how well it works and/or they think the initial setup is a pain.  The setup does have a few steps but actually isn’t difficult.  This video walks you through all of the steps to install the Zend debugger.

Click here to view the embedded video.

Download links referenced in the video:

Zend Studio Web Debugger (Apache Module):
http://www.zend.com/en/products/studio/downloads

Zend Debugger Plugin Install Site (Eclipse Plugin):
http://downloads.zend.com/pdt

Optionally you can download the Zend debugger plugin and install it manually by copying the files to your Eclipse folder instead of using the “Install Site”  That can be downloaded here: http://www.zend.com/en/community/pdt 

Configuration text for php.ini

zend_extension=/usr/lib/php/extensions/ZendDebugger.so
zend_debugger.expose_remotely=always
zend_debugger.connector_port=10000
zend_debugger.allow_hosts=127.0.0.1/32,192.168.*.*,10.*.*.*

The version included with WordPress (as of 3.1.3) is 1.2.  However this is not the most recent version of SimplePie.  Attached to this post is SimplePie 1.3-dev which is compatible with version 1.2 but addresses various issues.

If you are having trouble parsing feeds, you may try downloading this file and replacing the file /wp-includes/class-simplepie.php with this one.  Be sure to back up your original file in case anything goes wrong.

Click the package below to download the file:

// ExceptionThrower example
// source for ExceptionThrower is at the bottom of this post
 
ExceptionThrower::Start();
 
try 
{
	include_once("missing/file.php");
}
catch (Exception $ex)
{
	echo "I HANDLED THIS ERROR: " . $ex->getMessage();
}
 
ExceptionThrower::Stop();

Errors cannot normally be handled with a try/catch.  The PHP compiler takes over, takes the script out of your control and then either directly injects text to the browser and/or halts execution.  PHP allows you to alter this behavior using the set_error_handler function, but it seems better as a global error handler and not for catching expected errors in a small block of code.  Most runtime errors, though, can be intercepted and re-thrown as an Exception so that they can be handled consistently. Unfortunately E_FATAL as well any any error that is raised at compile time cannot be intercepted (such as those thrown by require_once). However compile-time errors often indicate a syntax error.

The example below shows how to use a utility class called ExceptionThrower to handle a single function call and then re-set the PHP error handler as it was.  By default this handles all runtime errors except E_DEPRECATED (though PHP earlier than 5.3 doesn’t define E_DEPRECATED so those errors are caught but ignored). You can turn this off for even stricter error handling, however a lot of third-party libraries will use deprecated methods and you may not wish to port them all.

// ExceptionThrower example:
 
ExceptionThrower::Start();
 
try
{
	include_once("missing/file.php");
}
catch (Exception $ex)
{
	echo "I HANDLED THIS ERROR: " . $ex->getMessage();
}
 
ExceptionThrower::Stop();
 
/**
 * Utility for catching PHP errors and converting them to an exception
 * that can be caught at runtime
 * @author Jason Hinkle
 * @copyright  1997-2011 VerySimple, Inc.
 * @license    http://www.gnu.org/licenses/lgpl.html  LGPL
 * @version 1.0
 */
class ExceptionThrower
{
 
	static $IGNORE_DEPRECATED = true;
 
	/**
	 * Start redirecting PHP errors
	 * @param int $level PHP Error level to catch (Default = E_ALL & ~E_DEPRECATED)
	 */
	static function Start($level = null)
	{
 
		if ($level == null)
		{
			if (defined("E_DEPRECATED"))
			{
				$level = E_ALL & ~E_DEPRECATED ;
			}
			else
			{
				// php 5.2 and earlier don't support E_DEPRECATED
				$level = E_ALL;
				self::$IGNORE_DEPRECATED = true;
			}
		}
		set_error_handler(array("ExceptionThrower", "HandleError"), $level);
	}
 
	/**
	 * Stop redirecting PHP errors
	 */
	static function Stop()
	{
		restore_error_handler();
	}
 
	/**
	 * Fired by the PHP error handler function.  Calling this function will
	 * always throw an exception unless error_reporting == 0.  If the
	 * PHP command is called with @ preceeding it, then it will be ignored
	 * here as well.
	 *
	 * @param string $code
	 * @param string $string
	 * @param string $file
	 * @param string $line
	 * @param string $context
	 */
	static function HandleError($code, $string, $file, $line, $context)
	{
		// ignore supressed errors
		if (error_reporting() == 0) return;
		if (self::$IGNORE_DEPRECATED && strpos($string,"deprecated") === true) return true;
 
		throw new Exception($string,$code);
	}
}

You can alternatively call ExceptionThrower::Start() at the beginning of your script and never call ExceptionThrower::Stop() This would cause all PHP errors to be converted into Exceptions for the duration of the script.  If you don’t have any other error handling, I think this is a decent approach.  As a warning, though even E_NOTICE errors will cause execution to halt.  That’s not necessarily a bad thing in my opinion because it may lead you to find bugs that you didn’t know existed.

Runtime errors don’t necessarily indicate a bug.  They can be caused by anything from bad user input to a database connection issue, missing libraries, etc.  They could be a bug, but they may simply be a known state that can be handled.  Runtime Errors come in a variety of flavors such as E_ERROR, E_WARNING, E_NOTICE and others.  Depending on your server configuration you may see them in your browser output or error logs.  In most cases they halt the execution of your script and lead to half-rendered pages or blank pages.

Be aware that only one function can assigned as the error handler at a time, so if any other libraries call set_error_handler, they will take over the error handling for the entire app.  When you call restore_error_handler, PHP will set it back to whatever it was previously.  In other words it is a last-in, first-out (LIFO) stack.

Please don’t interpret this article as encouragement to suppress PHP errors, mask bugs or allow your code to go into an unknown state.  The point here is exactly the opposite of that.  It is to prevent a PHP runtime error from halting your script and/or barfing all over your page with warnings.  The goal is to catch expected runtime errors in order to keep the application in a known state, close open resources, rollback transactions, log the error, render a decent error page, etc.

I’m really impressed with the WordPress plugin API and distribution system.  It’s well organized with great documentation.  I was psyched to see the little “upgrade available” button next to my own plugin once I published it to the WordPress plugin directory!  Even though I prefer object-oriented code, I have to admit the procedural style of WordPress code is consistent and easy to follow.

In the process I also had get my hands dirty with SimplePie RSS library that WordPress uses.  It does a nice job of parsing all kinds of RSS but I found it a bit difficult to debug feed errors.  Its also a little touchy with eBay feeds and there seems to be some glitches using set_feed_url(), so I would up accessing feed_url directly, which doesn’t seem right.  But it works so it’ll have to do for now.

If you give the plugin a try, feel free to leave a comment on directly the HungryFEED page.

The solution so far is to write a custom authentication plugin plus a component for Joomla.  The plugin handles sign-on and the component allows us to render basically anything within the content area of the Joomla site.  I was able to get proof-of-concept running today and not only does the Phreeze code render correctly inside the Joomla system, it wasn’t even necessary to merge the Phreeze code, it runs just fine with the source code in a separate folder from Joomla.  The component just has to do a little magic and configure some paths to make Phreeze happy.

This seems to be one of those rare moments where strict coding practices actually pays off.  I designed Phreeze to be an extremely modular MVC / ORM with the idea that we might one day use another rendering engine, or switch data engines.  We’re even in the process of swapping out direct database connection with REST services with no change to the views, which will be exciting.  Dependency injection is used for all the various parts so you can swap anything.  But I hadn’t really considered running the entire framework within another system.  So I was somewhat surprised when the code just ran with almost no configuration.

The biggest problem is with relative URLs.  Joomla I must say is pretty great about passing control to a component and then staying out of the way, even if you throw lots of weird querystring parameters on the end of the URL.  However, the relative paths to scripts, styles, images, etc are proving to be problematic.

I haven’t decided on the best approach yet but I’m considering simply writing new Views for Joomla.  This allows us to re-use all of our Model and Controller code.  I’d prefer to just use everything exactly as-is in each application but in some ways it might make more sense for the apps to render themselves differently when inside the Joomla system vs when running stand-alone.

Phreeze has a URL writer class which does help to solve the relative URL problem, however we didn’t use it consistently in all the views and so there is some cleanup to do.  Also this class isn’t accessible from within static JavaScript code, so that might get messy with some of the more advanced pages that make a lot of Ajax calls.

This is possibly my nerdiest post ever but it’s exciting to spend so much effort at writing adaptable code and then finally the day comes where you get to see it work in a totally unexpected way.

As you go through this walk-through, it helps to understand that WordPress MU was originally designed to create a branded, automated community of blogs using sub-domains (i.e. third-level domains) such as user1.wordpress.com, user2.wordpress.com, etc.  You can sign up on wordpress.com right now and get your own instant blog, hosted on their servers.  You become a part of the wordpress.com community.  WordPress MU was designed to allow you to create your own communities under your own domain name branding.

This walk-through addresses a slightly different type of user which is perhaps a server admin or simply a person who runs several blogs.  There is no “community” and you don’t allow anonymous users to stop by and create a blog.  You might currently have WordPress installations on multiple servers with totally unrelated domains.  Keeping the code and plugins updated for multiple blogs gets to be a hassle, so the idea of a single, centralized WordPress install is appealing for maintenance reasons.  Thanks to WordPress’s flexible architecture you can do this, but it’s not part of the original design.

The reason I write all of this is to hopefully explain why SLDs are outside the scope of WordPress’s original design.  You can still set it up without understanding any of this, however it will make things easier if you know how the pieces fit together.

Requirements

To keep this simple I’m only going to write about the multi-site configuration.  I’m assuming you know how to install WordPress, edit config files on your server, create a MySQL database on your host and map sub-domains.  These things may be done differently depending on your host so you will need to do the research for your own host server.  If you run your own server you may have to know how to configure it for multiple domains as well.

DNS Configuration

Again, I’m not going to get into DNS configuration.  However, I will say that a simple setup is to simply point all of your domains to the same IP address and let WordPress do the rest.  You can also assign one domain an IP and then park each additional domain onto this one, which may save hosting fees.  WordPress relies on the hostname, so it doesn’t matter how you’ve configured Apache or IP addresses, so long as the domain maps to the physical location of your WordPress install.

As a handy tip – you can edit your local hosts file to point a domain to the IP of your WordPress installation and WordPress will install easily this way.  This is a great way to experiment and migrate over an existing site without taking the domain name offline.  If you don’t understand what this means, then don’t worry about it!

1. Install WordPress

Install using all defaults is fine.  You should install this onto the domain that you plan to use as your “master” domain.  My recommendation is to install it at the top level of your domain, for example “domain.com” (without the “www” prefix).  If you plan to use sub-domains for different sites then this will keep things simple.  You can always add “www” during site configuration, but you can’t remove it from your sub-domain sites if it was installed that way.  For example your sites will look like this: site1.www.domain.com  instead of simply site1.domain.com.

Verify that WordPress is running but don’t bother putting any content in at this point.  In the next few steps we’re going to enable new menu items one after the next that are necessary to use the multi-site feature.

2.Enable the WordPress Multi-Site Feature

Assuming WordPress is running, edit wp-config.php and add the following line:

define('WP_ALLOW_MULTISITE', true);

After you add this line and save the file, return to the WordPress Admin page and look for a new menu item Tools->Network.  (If on 3.1 then instead you will see a new link next to the Logout link called “Network Admin” and from there go to Settings -> Network Setup) Navigate to this new menu and you’ll be prompted to “Create a Network” in order to enable the multi-site feature.

You have some choices as to whether you want to use sub-domains or sub-folders for your network.  Leave all the defaults and choose sub-domains.  We’re going to be using separate SLDs anyway so choosing sub-domains seems to make more sense to me.  If you choose folders, you’ll be on your own from this point forward.

Once you enable the network, you will be given configuration text that you must copy and paste into an .htaccess file and some additional variables to be pasted into wp-config.php.  Do this as directed on the Network page.

In WordPress 3.0 – after you edit these files and re-login you should see another new menu “Super Admin” which is above the dashboard menu.  Your site is now ready for multiple sites.

In WordPress 3.1 The Super Admin menu has been replaced with a separate “Network Admin” screen which you use instead of the “Super Admin” menu.  The link to this is located in the upper-right part of the screen next to the “Log Out” link.  This link will let you toggle in/out of network admin mode.

3. Install Plugin WordPress MU Domain Mapping

At this point your server is already setup to handle multiple sites, but we need to install a plugin in order to support SLDs.  The plugin to use is called “wordpress-mu-domain-mapping“  This plugin also includes a special file known as a “drop-in” which must be manually copied and hooks into the lower levels of the WordPress API.

You can install this plugin by manually uploading it, or through “Plugins->Add New.”  Just make sure
you install version .052 or higher.   After you have installed it, go ahead and activate the plugin.  You’ll notice that plugins now have an option to “Network Activate” which activates a plugin for all sites.

Once the plugin is installed, you need to manually install the Sunrise “drop-in”  which is included with the plugin source files.  You may either copy sunrise.php from /wp-content/plugins/wordpress-mu-domain-mapping/ to /wp-content/ or if you prefer  you can create a symbolic link (for example ln -s plugins/wordpress-mu-domain-mapping/sunrise.php.  I prefer the link myself).

Once you’ve copied or linked the file, you have to edit wp-config.php one last time and add the following line which will tell WordPress to activate the drop-in:

define( 'SUNRISE', 'on' );

Once you re-load the console you’ll once again have some new menu items.  This time they appear under the Super Admin (Network Admin in 3.1 or higher) menu and they are Domain Mapping and Domains.  The Domain Mapping has some settings that don’t actually need to be changed.  The Domains page is where we’ll map SLDs to a site (in the next step).

4. Create a Second Site

At this point your server is fully ready to support SLD sites, you just need to know how to add them.  The basic concept is that you create a site first using WordPress’s normal functionality.  Then you using the domain mapping plugin to map the SLD to the new site based on it’s Id.  Because WordPress doesn’t yet natively support SLDs, you have to do a little fudging with the forms.

First, under Super Admin (or Network Admin) go to the Sites page.  It is slightly confusing because you have to choose a sub-domain for your site, even though we’re going to use a SLD.  That’s ok, just enter whatever you want as the sub-domain and add the site.

Now that you’ve added the site, you can click “Edit” under the new site and this will bring up a long page with lots of settings.  Don’t worry about changing everything right now but you do want to change these two fields: Domain and Fileupload URL.  These need to be changed to your new SLD:

At some point once WordPress natively supports SLDs you would probably be done at this point.  In fact you will be able to visit your new site if your domain is already configured, but you won’t be able to log into the admin panel for the site.  So we need to map the domain over to the new site.

Before you leave the Sites page, make a note of the ID of your new site.  (In the screenshot above, my site “whatever” has the ID of “8″).  If it’s a new install, then your ID will probably be “2″.

Head to the Super Admin -> Domains page (in 3.1 this is Network Admin -> Settings -> Domains) and there is a form at the bottom to add a new Domain.  Leave the Primary checkbox checked.  Enter your site ID from above and the domain.  Click Save to add the mapping.

At this point you’re done and you should be able visit your site using your SLD as well as login to the admin panel.  I hope this tutorial worked for you and helped you to understand how WordPress MU feature works as well as some of it’s current shortcomings.

Please leave a comment if you have any suggestions to make this walk-through easier.