There are probably more than a few naive programmers who would read results like this and start to avoid these constructs in their own code for performance reasons. These are the same kinds of people obsessing over a few single or double quotes, who eschew “slow” objects in favor of switch statements that are many times slower than the polymorphic method calls they are trying to avoid.

But, that’s not the end of the story. Larry ran his benchmarks using 2,000,000 iterations. The N really matters here. Sure, iterators are slower than arrays, but you aren’t going to be iterating over two million things. I tend to fetch my database records in lots of 25 or 50. You aren’t going to be making two million invocations of __call. But how many will you make? Under what value of N does the performance of these techniques cease to matter? Is it ten, one hundred, one thousand, or ten thousand? You may be surprised at how few calls your program actually does and how little impact it has on performance.

As Wez and Travis point out in their comments, profiling is the way to find out the potential impact and to discover your true N.

Paul M. Jones has a good example of what I’m talking about. There, call_user_func_array appears to be a bottleneck, but it turns out that its the function being called, htmlspecialchars, not the calling process that consumes the balance of the time. In that case, the function was “only” called 300 times. I find that order of magnitude to be fairly typical. Something to be aware of, perhaps, but not something to obsess over.

The scale that Cal is talking about is actually better known as modularity:


| Few large modules ---- Sanity? ---- Many Small Modules |


If you haven’t listened to Alan Kay talk about the benefits of many small modules, you should do so now. Alan Kay coined the term Object Oriented. Love OO or hate OO, if you have an opinion on it, you should know what he was thinking. Hint, it wasn’t C++.

On the other end of the scale, One Giant Function is generally known as Big ball of Mud(PDF) Here is Brian Foote’s presentation on the paper (read the paper first).

You may prefer to use one of the 3rd party distributions of PHP, such as MAMP, XAMPP or Marc Liyanage. This is a guide to using the version of PHP that comes with 10.5.

Enable Developer Tools

These steps may not be strictly necessary for this process, but I find it useful to do them.
First, enable your root password.
You may also want to install XCode Tools from your Leopard disk (or grab the latest from Apple developer tools). The tools are required is you are going to compile any extensions for PHP.

Editing Configuration Files

We will have to edit several configuration files that exist as part of the unixy underpinnings of OS X. I’m going to recommend the free text editor, TextWrangler for this purpose. Normally, the finder hides the configuration files from view. However, in the finder, you can use the “Goto Folder…” option under the “Go” menu to view these files. This option if available via command-shift-G. Actually, this option is available in any file open dialog in OS X via command-shift-G. In addition, Text Wrangler will allow you to browse these files with its “open hidden…” option. But, the much easier option is selecting “Open file by name…” (command-D) and just typing the full path and filename. To save many of these files, you will need to enter your root password. Be Careful.

Enabling PHP

PHP is installed in Mac OS X by default, but not enabled. To enable it, we must edit the apache 2 configuration file, which is located at /etc/apache2/httpd.conf. Find the line which loads the PHP 5 module, which looks like this:

#LoadModule php5_module libexec/apache2/libphp5.so

The line is currently commented out. All we have to do is remove the comment symbol, #, so the line looks like this:

LoadModule php5_module libexec/apache2/libphp5.so

Save.

Starting Apache

Go to the sharing panel in system preferences and enable “Web Sharing.” This will start the apache server.

Another way to do this is to type the following in the Terminal application:

sudo apachectl start

You will be prompted to enter your root password. After that, your apache server should now be running. If you need to restart the server from the terminal, you can type this:

sudo apachectl restart

If you find this tedious to type, there is a script that you can download to do this later in this post.

Visiting our Web Site

Now, lets check our work. In the sharing panel, you can click on the URL under “Your computer’s website.” Alternatively, in the web browser, go to the url http://localhost/. localhost is a special name that means “My computer.” If your web server is working, you should see a page titled “Test Page for Apache Installation.” If you go to http://localhost/manual/, you can read an Apache 2.2 manual, hosted from your own server. But, this don’t tell you that PHP is working.
For that, we’ll have to create a very simple php program. Create a new file in TextWrangler and type the following:

 
< ?php phpinfo(); ?>
 

Showing the World

For security purposes, you should consider that anything you put in your WebServer/Documents folder will be available across the web. If you have information that you want to keep private, think twice about putting it there, unless you know how to protect it.
But, if you want people to see the pages that you are sharing, there can be a few obstacles. You can give out the URL that is listed in the sharing control panel under “Your computer’s website.” However, if you are behind a NAT router, such as I am, this IP address based url will only work for other computers on your network and not for the internet as a whole. You may have to configure network router or firewall in order to discover your true ip address and to route web server requests to that IP to your computer. Doing this is beyond the scope of this tutorial.
Additionally, IP address based urls don’t make good urls to share. IP addresses can change. If you plan to host a permanent web site, you may want to purchase a domain name and point it to your Mac. This also, is beyond the scope of this tutorial.
Perhaps the best option is to purchase both a domain name and professional hosting. Apache based PHP Hosting is widely available and cheap. You can get support from a good host on uploading your files to the remote server. I’m going to presume that you will use one of the many excellent PHP hosting options and are only configuring PHP on your own machine for education, testing or development purposes.

Enabling a Personal Website

If you clicked on the URL under “Your Personal Website,” you might have gotten a page that says forbidden. This is because in the default configuration in Leopard, unlike in Tiger, does not allow Apache to serve documents from home directories. If you want to enable this feature, you have to create a new Configuration file.
Create a new file with the following contents and save it to /etc/apache2/users/jeff.conf.

 
<directory "/Users/jeff/Sites">
    Options Indexes MultiViews FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
</directory>
 

Virtual Hosting

If you want to experiment with or work on more than one site at a time, the single directory in WebServer Documents and the Personal Websites configuration don’t work well. Projects collide and files outside of your home directory can be harder to work with. The answer to this is to setup virtual hosting. Lets turn our Personal Website sharing solution into a virtual hosting solution that allows us to work with multiple websites as subdirectories of our Sites folder.
So, lets create a sample site, called mysite. We’ll create a folder called “mysite” as a sub folder of our Sites folder. Capitalization is important.
Now, we are going to want to access our site with an easy to use domain name, so that our url is http://mysite/. There is an easy way to create new domain names that are only for personal use. To do this, we can add it to our /etc/hosts file. Add the following lines at the end of this file:

# My local aliases
127.0.0.1 mysite

127.0.0.1 is a special IP address designation that never changes and corresponds to localhost to mean this computer. We are telling our Mac that the name mysite is hosted on the local computer. This rule is only in effect on the same machine. If you go to a different machine, you cannot use the http://mysite/ url.
Now we need to configure apache for virtual hosting. We are going to have to edit our /etc/apache2/users/jeff.conf file. Change the contents of this file to the following:

 
<directory "/Users/jeff/Sites/*/">
    Options Indexes MultiViews FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
</directory>
 
NameVirtualHost *:80
 
<virtualhost *:80>
    DocumentRoot /Users/jeff/Sites/mysite
    ServerName mysite
</virtualhost>
 

 
<virtualhost *:80>
    DocumentRoot /Users/jeff/Sites/myothersite
    ServerName myothersite
</virtualhost>
 

Sharing with the World, Part II

Sharing your virtual hosted sites with the world is more complicated if you don’t have a domain name setup. You can, however, add your hosts files entries to other computers that you want to share with. However, you have to change the 127.0.0.1 IP address to the IP address of your computer, taking into account any NAT.
There is a special case of this. If you are using parallels, perhaps for test viewing your pages in internet explorer, you may want your virtual hosted sites to be available. The good news is that Windows also supports a hosts file. Here is how to edit your windows hosts file. The big problem is knowing what IP address to use. You can’t use 127.0.0.1 on the windows side because that is the virtual windows machine, not your Mac’s address. You can use the IP address shown on your network system preferences panel, 192.168.1.100 for me. But, this number is subject to change and you will have to re-edit your hosts file on the windows side.
If you are using Parellels, be sure to upgrade to the new beta version for Leopard, build 5540. Once you’ve done that, if you visit the network panel in system preferences and select the “Parallels Host-Guest” network, you will see the IP address that parallels assigns to your host machine. (assuming you are using Shared Networking.) You can then use this IP address in your windows hosts file. You may also be able to change “Using DHCP” to “Using DHCP with Manual address” and re-entering this number if you have a problem with the number changing. Here, my number is 10.37.129.3:

Installing MySQL

MySQL has a binary distribution for Mac OS X. They also have reasonably good documentation on installing MySQL on Mac OS X for their distribution. Note that Leopard specific packages for MySQL have not been created yet.

Starting MySQL

So far, the MySQL preferences panel from the Tiger release is broken and does not correctly start and stop MySQL (bug report. You can do this from the terminal window with

sudo /usr/local/mysql/support-files/mysql.server start

To shutdown the server type:

sudo /usr/local/mysql/support-files/mysql.server stop

If you find this tedious to type, you can download WebDevCP, which is a small AppleScript application that I made. Launching WebDevCP launches both Apache and MySQL. Quitting the application shuts them both down. usually. Launching and quitting requires a password. No warranty on this thing. It was just something I was using personally and figured others might find useful.

Bring the mysql.sock to PHP

One problem that has come about with MySQL and Leopard is the location of the mysql.sock file. Previously, the default location for this file was in the /tmp directory. That location has now moved to the /var/mysql directory. PHP will look for it there. Unfortunately, the default location from the MySQL will still place it in the old location. We can fix this by creating a my.cnf configuration file in the /etc directory. Save a file with the following contents to /etc/my.cnf:

[client]
socket = /var/mysql/mysql.sock

[mysqld]
socket = /var/mysql/mysql.sock

In the terminal window, type the following commands to create the directory for the sock file:

sudo mkdir /var/mysql
sudo chown _mysql /var/mysql

One drawback to this is that if you have installed the MySQL GUI tools, they will look for the mysql.sock file at the old location. You can enter the new socket in the connection dialog under More Options, there is a box labeled “connect using socket.” Just enter /var/mysql/mysql.sock.
Another solution is to change the php.ini file to expect the socket in a different location. I’m going with the my.cnf option because I expect the MySQL will have a Leopard version out in a few days that changes the default location.

Where is PEAR?

OS X has traditionally had problems with PEAR. Many point updates would overwrite the included version of PEAR with an older, and perhaps insecure version. Sadly, Apple has fixed this by not including PEAR at all in their OS. This is a big inconvenience for people wanting to use Apple’s default version of PHP, versus a third party distribution. So, lets get PEAR installed. Type the following in the terminal window to download the PEAR installer:

curl http://pear.php.net/go-pear > go-pear.php

after that, type

sudo php -q go-pear.php

To run it. Hit enter to select the default locations. PEAR will be installed, but it won’t be ready to use until we modify our php.ini file.

PHP .ini configuration

Now we need to make some changes to our php configuration file. Leopard has an empty configuration file by default, but provides a file which you can use as a template. From the terminal window, type:

sudo cp /etc/php.ini.default /etc/php.ini

Now, edit the /etc/php.ini file. Find the include_path setting:

;include_path = ".:/php/includes"

And change it to

include_path = ".:/usr/share/pear"

This enables our PEAR installation. You may also want to make some changes which will improve your ability to debug PHP. FInd the line that says

log_errors = Off

and change it to

log_errors = On

You have to then restart Apache for these PHP changes to go into effect.

Errors and Omissions

Thats all there is to using the version of PHP delivered with OS X. If you find this confusing, you are probably better off with something like XAMPP or MAMP. I’ll probably end up compiling my own versions of PHP, but that is a different blog post. I’ve already had problems with this configuration when I tried to install XDebug via PECL. One last thing, if you run into problems, you can check the apache2 error_log file using the Console application.

For support, try the Sitepoint forums or Apple’s Discussion Forums.

< ?php
function test($arg) { echo "talk like a pirate."; }
test();
?>

Warning: Missing argument 1 for test() in /usr/bin/- on line 2

The error message here is reported at the position of the definition of the function, but really the error was in how the function was called. The required parameter to test was not passed. This error can be annoying, forcing you to consult a stack trace to find the actual error location. Something some beginners may not know how to do.

However, if you run the same message in PHP 5 (tested on 5.2.2):

Warning: Missing argument 1 for test(), called in /Users/jeff/- on line 3 and defined in /Users/jeff/- on line 2

Sweet improvement!

One more reason to ditch PHP 4 and go php 5.

One of my main goals was to meet some of the folks at php|architect. I’ve been writing the Test Pattern column for them for over a year now. I was finally able to put faces to the names that I keep seeing in my email box. Actually, one of the cooler things about the conference was meeting people who I’m familiar with from online, either from forums, IRC, mailing lists or blogs.

I’d like to thank everyone who attended my sessions. Here are the slides from each session:

• Writing Maintainable PHP Code (PDF) - based on my March 2006 column.
• Dependency Injection (PDF) - based on my June 2006 column.
• Exceptional PHP (PDF) - based on my December 2006 column.

 
function set($name, $value);
function get($name);
 

Some times there are some ancillary methods to deal with unsetting, checking for existence, setting via an array, or dealing with references in PHP 4. They can really clutter up the definition of a class. That’s not good. All this code is fairly standard, too, but it gets duplicated on every class that does this. That’s not good, either.

Oh, I’ll solve this problem by making a base class, some may say. Wrong. This a very feeble reason to spend your one shot at inheritance. Trust me, I know, I’ve done it.

I think the idea is to make the class extensible. But PHP is really ok with just setting new properties on a class.

 
$obj->foo = 'bar';
 

Another variation of this pattern is to use setXXX($name, $value) or setYYY($name, $value) methods. This happens alot with “options” or “vars” or “properties.” It also happens on request wrapper classes. To me this looks like there is an object here just begging to get out for each XXX and YYY.

 
$obj->xxx->prop = 'foo';
$obj->yyy->prop = 'foo';
$obj->zzz->prop = 'foo';
 

Since I’ve started eliminating these in my own code in favor of direct properties, intermediate objects or __set and __get, I feel I’ve seen nothing but positive results. Try it. You may like it, too. Let your properties be properties.

UPDATE:
From reading the comments, I think there was some confusion about what I meant in this post. I am not talking about using naked properties instead of accessor methods. I’m not talking about accessor methods at all in this post. A specific accessor method, such as

$obj->getFoo()

$obj->get('foo');

Even on projects with extensive generated documentation, I find that kind of documentation to be of extremely low value. The problem with inline API documentation is that there is no sense of priority. Developers are encouraged to document every element that can possibly be documented. Then, when the documentation is generated, there is no way to distinguish the important from noise.

Another problem is restating the obvious. When a property or method really is well named, there may not be much more to say in the docblock. But, the mechanics of docblocks invites the programmer to say it anyway. So, you end up with comments like “$widget the widget.”

Duplication is also a significant problem. If you inherit from a base class or you implement an interface, there is a tendency to copy and paste the doc block from the parent to the children. This is an obvious maintenance problem. In fact, this is one of the major problems with comments. If comments restate what the code does, its a form of code duplication. When the code is changed, it requires changes in the comments. In this sense, comments make code harder to maintain.

Lately, I’ve been trying to curb the attractive nuisance aspect of docblock comments by replacing docblocks with comments like

 
// Definition in parent
 

 
// docblock intentionally omitted.
 

Well, if docblocks are so bad, what is the alternative? Well, I’ve tried a few, including using a wiki for API documentation. Here is the problem. If duplication between the comment and the code is created by inline documentation, that maintenance problem becomes significantly worse with distance. If the documentation is external to the code, that distance really harms the ability to keep the documentation in sync with the code. So, docblocks are bad, but everything else is worse.

Docblocks were popularized by Sun and Java (or maybe Donald Knuth). But when sun was documenting their Java APIs with docblocks, they had a professional documentation team to do the work. When teams that don’t have a dedicated documenter role use these tools, I think they fall short.

So what is the solution? I’d like to see better techniques and conventions for solving the problems of docblocks: avoiding duplication, avoiding restating the obvious, and avoiding the tendency to docblock everything thats docblockable. Maybe there are more successful documenters out there who are handling these API documentation anti-patterns better than I am. I’d sure like to hear how.

BBCODE was designed for this purpose. There is no actual standard, but the core syntax seems fairly uniform. It’s good for those used to forums, where it seems to norm.

HTML markup is nice because it is a standard, even if varying subsets are supported. Learning a little HTML isn’t going to hurt anyone, at least for the next 20 years or so. The problem is that HTML was never intended to be hand edited. The syntax is not the most inviting, and different HTML-like markup languages handle whitespace differently than the HTML standard.

Wiki markup syntaxes were designed to be human friendly. The main problem I have with wiki syntax is that there is no standard. It seems like every wiki has a different way to formulate a link, for example. I guess there is some progress with Wiki Creole, but I still have a bad taste in my mouth.

The other problem I have with wiki markup is that I find it to be non-deterministic. When I edit any given wiki and try to use more than basic formatting, I never know what I am going to get. Most of the markup processing engines for these wikis are impenetrable morasses of regular expressions. It can be hard to gauge interactions. Are you really sure they are secure?

Speaking of impenetrable morasses of regular expressions, have you ever looked at WordPress’s input path? I’m sure every one with a WordPress blog who likes to blog about PHP code knows that it is a code eater. I’ve been particularly disappointed with WordPress in this area. Most the “code formatting” plugins still have problems protecting code from WordPress’ heavy hand.

But the WordPress preg_replace gauntlet doesn’t just mangle code. I have a post which has been sitting in draft mode for several weeks because I can’t figure out how to give it the proper markup. WordPress is somehow taking my perfectly balanced input markup and producing “unbalanced” output markup. I haven’t yet tracked down the problem to either submit a fix or to do a good bug report. Frankly, I’m not looking forward to trudging through all those regular expressions.

In Chris’ post, he takes the regular expression approach. Folks in the comments have pointed out a few problems with his approach, including the problem of interleaved tags. If you can’t tell by now, I am not a fan of the regular expression gauntlet approach to markup languages. I prefer a defined syntax and a traditional computer science style parser (which may use regular expressions).

The other must-have is a preview option. With so much variation in markup languages, not having a preview leaves the user to play Russian roulette with their submitted content. I’ve talked about that before in the usability of input filtering. This is another area where WordPress leaves the user high and dry.

The complex input path in WordPress combined with its reliance on global variables seems to leave it unable to do an in-page preview. The admin area preview is an IFRAME so that it launches a separate request. The various live preview plugins are JavaScript based and don’t work when it is disabled. They also don’t pass the input through the same input path that WordPress uses, so they are not a true preview.

I don’t mean for this to be a WordPress rant, on the whole, I like WordPress. Rather, I just wanted to point out how hard it can be to do good input filtering, that is safe, reliable, deterministic, and usable.

I have a great fondness and respect for the old Object Pascal based Delphi. Delphi’s VCL has been influential, inspiring the GUI components in Java. And, of course Ander Heijlsberg went on to put a huge stamp on C# and .NET that would be familiar to any Delphi programmers.

I’ve always admired this approach of extending the language syntax to make common things easy and for the integration between the language and the tools. In Delphi, this was evidenced by the excellent properties support. Six years later, this is the feature I miss the most in PHP. This language extension approach has seen its culmination in C# and LINQ. It almost pains me to say it, but the cutting edge of commercial language design is at Microsoft now.

On the other hand, I’ve never had that much respect for Borland as a company. We were big enough to have Borland representative’s come to our office and try sell us their products. They were terrible at the mechanics of selling into big companies. I was in their beta programs. I went to their conferences. I’ve never had any sense that they know what they are doing business wise. Inprise? What were they thinking? Now here they are, just having gotten their asses kicked by eclipse in the Java IDE space and what are they working on? They release an IDE for PHP, just as Zend is embracing Eclipse in the PHP space. Brilliant!

I don’t quite know what Delphi means now. To me, its always been and IDE plus Object Pascal. What is it now? I also don’t quite know what Borland has become. Is it CodeGear now? I guess that the Delphi for PHP IDE comes from Quadram and their now discontinued QStudio product. And the VCL is their WCL (no linkage found). Anytime I’ve been touched by the corporate entity that was Borland, confusion ensued. I’m confused now.

It appears that the PHP version of the VCL will be released on open source. There is nothing at the sourceforge project, yet, but I’ll be interested to see what it looks like, if only for old times sake.

The Delphi tool approach was to serialize an object based representation of an application, then offer tools to create that serialized representation, and to load that representation at run time. In Delphi, that serialization was done into the form files (.DFM). I’ll be interested to see how Delphi for PHP does it. Perhaps, this is an area where the Eclipse PHP Development Tool can learn. I know that I definitely had Delphi in mind when I was writing my column on Object Serialization for this month’s php | Architect.

Meanwhile, if you want to see the Delphi influence in PHP with code that you can download today, take a look at the Prado framework, which I imagine to be like the VCL for PHP, but without the supporting IDE.

This is a space I’ll definitely be watching.