By combining this extension, which sits on top of Firebug, with a server-side library, your PHP scripts will be able to send debugging information to the browser, handily encoded in the HTTP response headers. Once you’re set up, you can log warnings and errors in your PHP scripts to the Firebug console, just as if you were developing JavaScript.

To start, you first need to install the FirePHP extension from Mozilla’s Firefox Add-ons site. This requires that you already have Firebug installed. Once FirePHP is installed, when you next open your Firebug panel, you’ll now see an additional blue bug. Click on that bug and a menu will appear allowing you to enable or disable FirePHP:

This, of course, won’t do anything yet. You also need to install the FirePHP server-side library, which is available here. This is a stand-alone version of the library that can either be downloaded manually or installed using PEAR. After that, you simply need to include the library in your code. There are also versions designed to integrate with various frameworks or content management systems, such as the WP-FirePHP plugin for WordPress or the JFirePHP plugin for Joomla. For the sake of this walk-through, I’ll focus on the stand-alone functionality.

Once you have the FirePHP library on your server, you need to include it in your script with a line like:

Because FirePHP sends its logging data via the HTTP headers, you’ll need to buffer your script’s output so that the response headers can include content generated further down the script. In PHP, this is accomplished by calling ob_start near the top of your script:

With these steps done, you can start using FirePHP. All you need to do is call the fb function with whatever you’d like to log, along with an optional label and an optional constant to define the message as a standard log, a warning, an error, or information. For example:

$var = array('a'=>'pizza', 'b'=>'cookies', 'c'=>'celery');
fb($var);
fb($var, "An array");
fb($var, FirePHP::WARN);
fb($var, FirePHP::INFO);
fb($var, 'An array with an Error type', FirePHP::ERROR);

This code will produce the following output in the Firebug console:

You can also use FirePHP to give you a trace of your application’s execution: by passing in the FirePHP::TRACE constant, you’ll get to see the line number, class name, and function name from within which fb was called. So this code:

function hello() {
  fb('Hello World!', FirePHP::TRACE);
}
function greet() {
  hello();
}
greet();

Will produce an output as follows:

This trace functionality can be fantastic for debugging more involved scripts, as it lets you know exactly from where your functions are being called.

Of course, you need to remember to remove your debugging statements before your code goes live!

There’s a lot more to FirePHP than what I’ve covered here. I’ve been showing you the simplified procedural API for FirePHP, but there’s a more advanced object-oriented API available with a number of additional features. You can learn all about it on the FirePHP site, so be sure to check it out.

Related posts:

1. User Errors in PHP
2. Serializing PHP data structures for Javascript
3. Useful in-browser development tools for PHP

But what if you need to split the content into two or more blocks? That might be necessary if your theme requires multiple columns or sections on the page. WordPress provides a get_the_content() function to return content as a PHP variable, but how do you determine where the divisions occur? There are a few solutions on the web, but most involve either:

1. Splitting the content at HTML tags such as h2 headings. Unfortunately, that requires the content author to know a little HTML and it’s not very versatile — you couldn’t allow two headings in one column.
2. Using a WordPress shortcode. That’s more flexible, but it still puts the onus on the content editor to remember and use the right code.

The WordPress <!--more--> tag may offer a better solution. It’s normally used to split a long article into two or more pages, but not all themes use that facility and it only works for WordPress posts by default (not pages). Using the <!--more--> tag offers several advantages:

• A “more” toolbar button is available in both the visual and HTML editing pane.
• Divisions can be placed anywhere in the content.
• It’s easy for non-technical users to understand how the content will be split.

To split your content, locate your theme folder (wp-content/themes), edit or create a functions.php file and add the following function within a <?php … ?> block:

// split content at the more tag and return an array
function split_content() {

	global $more;
	$more = true;
	$content = preg_split('/<span id="more-\d+"><\/span>/i', get_the_content('more'));
	for($c = 0, $csize = count($content); $c < $csize; $c++) {
		$content[$c] = apply_filters('the_content', $content[$c]);
	}
	return $content;

}

You now need to locate the theme files which call the_content() within the WordPress loop. You should find it in single.php and page.php since these are used to display single posts and pages respectively. It may also be found in index.php, archive.php and search.php, however, these normally show more than one article so be careful how multiple content blocks are handled.

Once you’ve found the relevant code, comment out the_content() and call the split_content() function. It returns the content as an array; each element contains a single content block split at the <!--more--> tag, e.g. $content[0], $content[1], $content[2] … etc. The HTML can then be output as required, e.g.

< ?php
// original content display
// the_content('<p>Read the rest of this page &raquo;</p>');

// split content into array
$content = split_content();

// output first content sections in column1
echo '<div id="column1">', $content[0], '</div>';

// output remaining content sections in column2
echo '<div id="column2">', implode(array_shift($content)), '</div>';
?>

I hope you find it useful.

Related posts:

1. The power of String.prototype.split() … almost
2. The WordPress Security Update
3. How to Expose PHP’s Private Parts

To understand why this helps, you need to know a little bit about how PHP works. PHP is a scripting language, like Ruby, Python, and Perl. This is great for developer productivity, as there’s no need for the  code to be compiled. The trade-off for this flexibility is in performance, with a scripting language requiring more CPU power and memory than a compiled language such as C++. What HipHop does is transform your PHP code into true C++ code, which can then be compiled into machine code. This is not the sort of thing you would do while developing, but when you are deploying your work you can compile it into the superior C++ code.

HipHop Performance Boosts:

• Web — 50% less CPU usage with the same traffic
• API — 30% less CPU usage with double the traffic

The performance boosts that Facebook has seen is based on its own real-world experience, with over 90% of Facebook servers being converted to HipHop code in the last six months. The benefits released were split into two categories, the Web tier and API tier, and the benefits witnessed for each. The web tier reduced 50% of server load with the same amount of connections, and the API tier saw a 30% decrease, even with a twofold increase in traffic. The difference is explained by the web layer requiring more presentation logic and more abstract information (related information) than the API tier.

What’s the catch?
You’ll have to avoid a few PHP functions, such as eval() and create_function(). Because of the dynamic nature of these functions, the HipHop team was unable to transform them into C++ code; however, these functions are rarely used in most PHP applications in general.

Currently your HipHop code has to run through a custom-written HTTP server bundled with HipHop; however, using HipHop code with Apache is high on the development road map.

While HipHop will increase the performance of your PHP code, it’s not necessarily going to be the silver bullet for your performance woes; for example, if your bottleneck is in your database performance, HipHop will be unable to help you. There’s no need to worry about it making your code slower though, as the entire PHP runtime has been emulated in a way that even the most complicated code will run at the same speed as pure PHP code.

Where can I find it?
HipHop will be released very soon to the open source community, but in the meantime you can read the full write-up on the Facebook blog, or view the Facebook presentation.

What do you think?
I’m interested in doing some benchmarks and seeing how HipHop performs with the SitePoint codebase. Do you think you’ll be checking it out when it’s released?

Related posts:

1. Free PHP Webinar: How to Increase Performance with Caching
2. OOP and Performance
3. Free Performance with MySQL Table Types

In the previous year, I have spent a great deal of time with Ruby on Rails, and one of the things that works better in the Ruby world is the package distribution system (gems, as they are called). A lot of Ruby developers make their libraries available on github, which until recently had an integrated feature to publish the code as a gem. Recently they discontinued this service and instead a dedicated site, gemcutter emerged. Gemcutter is strictly a package hosting service/channel.

I think services like these are an important reason why gems are so popular amongst Ruby developers, and I figured that PHP really needs something similar. So over the Christmas period, I began brewing a service, which is now stable enough that I’ll make it available to the community at large.

pearhub.org provides a place where you can register a project that is hosted on Github, Google code or similar (Currently only git and subversion are supported). The service will generate a PEAR package and put it on a PEAR channel. This means that installation and upgrade can be done from the PEAR installer. New releases are made by making a tag in the linked repository. Pearhub will check routinely for any new tags, and generate a new package if so.

I hope you’ll find it useful, and feedback is of course welcome.

Related posts:

1. Subversion gits the last train
2. GitHub Gist is Pastie on Steroids
3. Ruby On Rails Linkage: GitHub, Passenger and more…

In this tutorial we’ll build a page that gathers up the RSS feeds of all those little bits of your life and presents them all together in one spot. To do that, we’ll use SimplePie, a feed parsing class written in PHP. It’s powerful, it’s open source, and it’s easy to use. We’ll then hack on the output a little, and make it all look gorgeous with HTML and CSS. The techniques we’ll cover are also useful if you find that you need to aggregate RSS from many sources, like a news page. Let’s begin!

What You’ll Need

• The SimplePie library.
• A web server that’s capable of running it — there’s a compatibility test in the SimplePie package that will tell you whether your server is good to go.
• If you tweet, grab this function by Alison Gianotto to help auto-link those tweets
• Of course, you’ll need your trusty text editor!
• For brevity, some of the code is excluded from this tutorial. If you want to see the full picture, view the completed example or download it.

Let’s Begin

First, of course, we’ll need to identify the feeds we want to include on the page. Like I said, I have profiles in lots of places, but for now I’ll keep it short and sweet — I’ll grab my blog, Twitter, Flickr photos, and favorited tracks from Last.fm.

You’ll need to gather up the URLs for the feeds you want, and stash them someplace safe. To do that, look for RSS icons on the page or in your browser’s address bar. Paste those URLs in a text file for later reference.

Next, we’ll need to check that SimplePie is compatible with our hosting environment. There’s plenty of stuff in this download — for now, we can just upload the compatibility_test directory in a web-accessible location on the server, and take a look at it in a web browser. Hopefully, there’ll be a series of messages informing you that a number of dependencies are enabled. If so, it’s time to upload the rest of the library. (If you have a folder in your download called test, it’s safe to exclude that one.)

While you’re poking around in your web server, now’s a good time to set up a directory for SimplePie to use as a cache. You should make this directory writable. I’ve chosen cache.

Make a note of where you uploaded SimplePie, and your cache directory. In my case, both are in the same directory as where I plan to put my lifestream page.

Prepare Your Feeds

Let’s grab those feeds! Open up a new text editor and begin a new PHP file, which we’ll call lifestream.php. This will be the page that eventually shows our lifestream.

First, let’s include a very important component — the SimplePie library itself:

<?php
  require_once('./simplepie/simplepie.inc');

Now, we need to define a couple of important variables: the first is to define the cache location, and the second is to specify the amount of time (in seconds) we want to cache the feeds. Hitting feeds repeatedly is rude, and some feed providers will bar you for excessive feed requests. Also, if you have a busy site, it’s sensible to keep your resource consumption low. I’ve chosen thirty minutes, or 1800 seconds, which is a nice tradeoff between freshness and politeness. Here are those variables:

$cache = "./cache";
$duration = 1800;

Next, time to create some SimplePie objects. The easiest way to turn a feed into a SimplePie object is to call it in its short form: pass it a feed URL, the location of your cache directory, and the cache duration. All my objects look roughly like this:

$object = new SimplePie(
 "http://example.com/feed.xml",
  $cache, $duration);

You’ll see I’m passing those $cache and $duration variables in to save repeating myself. Create objects for each of your feeds — mine are called $blog, $twitter, $flickr, and $lastfm.

At this stage, since I’m going to be including tweets, I’m going to paste in Alison Gianotto’s twitterify function. This function simply accepts some text and looks for items that would be clickable in Twitter — references to usernames with @, tags with #, and regular URLs — and wraps them in nice hyperlinks. The function inserts hyperlinks with a target attribute; I’ve removed those from my example.

Create a Shell

It’s markup time! Create a HTML shell immediately below the closing ?> of your PHP script. In this example, I’ve just shown the contents of the body element for brevity, though of course I’d include a !DOCTYPE, head, and other necessities:

<h1>My awesome lifestream</h1>

<div id="blog">
  <h2>My blog</h2>
  <ul>

  </ul>
</div>
<div id="twitter">
  <h2>My tweets</h2>
  <ul>

  </ul>
</div>
<div id="flickr">
  <h2>My pictures</h2>
  <ul>

  </ul>
</div>
<div id="lastfm">
  <h2>My tunes</h2>
  <ul>

  </ul>
</div>

Reveal the Items

Now that we have a shell of a document, it’s time to start adding some more PHP to this page to loop through each of the items and echo the relevant parts of each item — titles, descriptions, enclosures, links, and more — and wrap the appropriate markup around them. To find out what’s available, examine the source of your feeds, and take a look at the SimplePie documentation, specifically the stuff that begins with get_. You’ll find a list here.

Thinking of my own four feeds, each set of items should be slightly different. With my blog posts, I’ll want to include a title, description, date, and hyperlink. In the Twitter RSS feed, the title and description are identical, so I’ll just use the title. For the Flickr items, I just want to show the picture. The tracks on Last.fm just need a title, link, and date. So, I’ll need to create four separate loops.

Here’s the loop to spit out my blog items, which I’ve placed inside the unordered list inside div#blog. This one’s fairly straightforward:

<?php foreach ($blog->get_items()
  as $item) : ?>
<li>
  <h3>
    <a href="<?php
      echo $item->get_link(); ?>">
      <?php echo $item->get_title(); ?>
    </a>
  </h3>
  <p>
    <?php echo $item->get_description(); ?>
  </p>
  <p class="date">
    <a href="<?php
      echo $item->get_link(); ?>">
      <?php echo $item->get_date(); ?>
    </a>
  </p>
</li>
<?php endforeach; ?>

This loop should generate a series of list-items like this, for each blog entry in my feed:

<li>
  <h3>
    <a href="http://example.com/blogentry/">
      Title
    </a>
  </h3>
  <p>Blog entry description text</p>
  <p class="date">
    <a href="http://example.com/blogentry/">
      01 January 2010, 12:00 am
    </a>
  </p>
</li>

Too easy!

When examining my Twitter feed, I’ve noticed that each tweet is prefixed with my name, a colon, and a space. In this instance, I’ll want to remove that text. I’d also like to convert those hashtags, username references and URLs into clickable hyperlinks. In this loop, when I echo the title of the feed item, I’ll wrap $item->get_title() in a str_replace statement, and then wrap that in the twitterify function:

<?php foreach ($twitter->get_items()
  as $item) : ?>
<li>
  <p>
    <?php echo twitterify(
      str_replace(
        "raena: ", "", $item->get_title()
      )
    ); ?>
  </p>
  <p class="date">
    <a href="<?php
        echo $item->get_link(); ?>">
      <?php echo $item->get_date(); ?>
    </a>
  </p>
</li>
<?php endforeach; ?>

Flickr feeds’ descriptions are less than ideal for my purposes: they include the text “username posted a photo”, the medium sized image surrounded by a link to the photo page, and the Flickr photo’s description. However, I’d just like to present the littlest version of the image and hyperlink, and use the title of the image as the alt text. Fortunately, Flickr provides the URL to the image in the form of an enclosure, so I’ll use that instead.

Flickr’s enclosures are still medium-sized, but I want the cute, square thumbnail. That’s as simple as replacing any reference to _m.jpg with _s.jpg.

<?php foreach ($flickr->get_items()
  as $item) : ?>
  <li class="item">
    <a href="<?php echo $item->get_link(); ?>">
    <?php foreach ($item->get_enclosures()
      as $enclosure) : ?>
      <img src="<?php echo str_replace(
        "_m.jpg","_s.jpg",
          $enclosure->get_link()
      ); ?>"
        alt="<?php
          echo $item->get_title(); ?>" />
      <?php endforeach; ?>
    </a>
  </li>
<?php endforeach; ?>

Finally, I only need the titles and dates from my list of loved tracks from Last.fm:

<?php foreach ($lastfm->get_items()
  as $item) : ?>
  <li class="item">
  <p>
    <a href="<?php
      echo $item->get_link(); ?>">
      <?php echo $item->get_title(); ?>
    </a>
  </p>
  <p class="date">
    <?php echo $item->get_date(); ?>
  </p>
   </li>
 <?php endforeach; ?>

You’ll find my completed example as lifestream.phps in the code download, or again, view it in full here. If you plan to use it as a basis for your own work, remember to change the placeholder feed URLs to your own!

When you’re done fine-tuning your items, it’s time to upload it to the web server, and view it in your browser. If all went well, you should see a series of unordered lists, each containing different goodies from those RSS feeds.

All that’s left now is to style the page and add any other interesting goodies you feel are necessary. In the example, you’ll find an extremely simple set of styles: feel free to use them as a basis for your own.

There’s More…

Of course, there’s plenty more to SimplePie than the very easy example we’ve looked at today. Dive into the wiki and see what’s possible — there’s heaps of support for enclosure display, the ability to merge multiple feeds into one giant stream, and easy ways to add social media sharing buttons to items. You’ll find some great examples of SimplePie-powered sites on the wiki. Enjoy!

Related posts:

1. SimpleXML and namespaces
2. New Article: Build an RSS DataList Control in ASP.NET
3. Build a Buzzword Bingo Card in PHP

First, a little background: at the time of our first Twitaway in 2008, Twitter HQ had been kind enough to relax the limit it places on the maximum number of Twitter direct messages (DMs) that it would allow us to send in a single day. To distribute the free PDFs, then, we simply wrote a PHP script that would look through our Twitter followers every few minutes, identify the new ones and send them a DM with the download link.

This time around, when we sat down to plan Twitaway 2009, it was clear our job would be more difficult. Much less cooperative than they had been previously, Twitter HQ stonewalled our requests to relax the daily DM limit—they wouldn’t even tell us what our daily limit was. For awhile there, we weren’t sure how we would be able to deliver a download link privately to our Twitter followers.

The solution finally came from Mal, a new developer on the team here at SitePoint HQ. We would use Twitter’s new OAuth support to request temporary access to your Twitter account, use it to verify that you were indeed following us, and then simply display the PDF download link in your browser. No DM required!

Of course, writing a PHP application that supported this OAuth-based workflow was a lot more complicated than writing a static web page with a “follow us on Twitter” link. Not only would it be harder to write, but it would be harder to handle large amounts of traffic hitting it, too.

So there we were: just past midnight on launch day of the Twitaway, and the application had stopped responding. Our monitoring systems made it clear that, while our PHP servers were weathering the storm nicely, the MySQL database server had spiked to 100% CPU usage, stuck its fingers in its ears and begun rocking back and forth, chanting “na-na-na-na-na-I’m-not-listening!”

As it turned out, this was an important lesson for our development team about the importance of choosing appropriate MySQL table types. Read on for how we solved the problem, and why we should have predicted it.

Choosing The Right Table Type

When we logged into the swamped MySQL server, we could see (using the SHOW PROCESSLIST command) that the overwhelming majority of the queries that it was receiving were for the database table we had set up to contain PHP session data.

By default, PHP stores your users’ session variables in files on the web server’s hard drive. In our case, however, we had multiple web servers that all needed to share the same session data, so we had configured PHP to store its sessions on the MySQL database server instead.

Unfortunately, we had failed to specify a table type when creating the session table in the database:

CREATE TABLE sessions (
  sesskey VARCHAR(32) NOT NULL DEFAULT '' PRIMARY KEY,
  expiry INT(11),
  expireref VARCHAR(64),
  sessdata LONGTEXT
);

MySQL supports a number of different storage engines. When you create a table, by default MySQL will use the MyISAM storage engine to create a MyISAM table. MyISAM is a relatively simple table type, which forgoes several advanced features in order to offer improved performance. In the early days of MySQL, the MyISAM table type was instrumental in making it one of the best performing databases around.

These characteristics would seem to make MyISAM a natural choice for something like a session data table. Unfortunately, MyISAM has an achilles heel: table-level locking. In order to write a change to a MyISAM table, MySQL must lock the whole table, preventing any other query from reading the table until the change is complete.

As thousands upon thousands of SitePoint readers flocked to our Twitaway site to claim their book, multiple PHP processes competed to create, update, and read session data in this single table. And because of MyISAM’s table-level locking, they had to do so one at a time, waiting their turn on an increasingly backed-up database server.

On the surface, the InnoDB storage engine would seem to be a poor choice for improving database performance. It supports a bunch of features that MyISAM doesn’t, including transactions and enforced referential integrity, and all the literature will tell you that writing data to an InnoDB table is slower than with a MyISAM table.

But where MyISAM has an achilles heel, InnoDB has a secret weapon: row-level locking. When writing data to an InnoDB table, only the affected rows are locked, not the whole table. Queries accessing other parts of the same table can happen simultaneously. In a situation like session data, where each browser request being processed is likely to relate to a different session, row-level locking is just what the doctor ordered!

With this in mind, you can probably guess how we cured our swamped database server. We simply converted the session table to an InnoDB table:

ALTER TABLE sessions ENGINE = InnoDB;

Instantly, the CPU load on the database server dropped to more reasonable levels, the Twitaway site came back online, and there was much rejoicing. We could have saved ourselves a lot of grief simply by specifying the table type when we first created the table:

CREATE TABLE sessions (
  sesskey VARCHAR(32) NOT NULL DEFAULT '' PRIMARY KEY,
  expiry INT(11),
  expireref VARCHAR(64),
  sessdata LONGTEXT
) ENGINE = InnoDB;

Switching to InnoDB got us through that first night, but by the next morning we were wondering if there might be an even better table type for us to use. After a little research, the Memory storage engine looked like a likely candidate.

If MyISAM sacrifices features for performance, the Memory table type takes this to extremes. Memory tables are never written to disk, so if you restart your database server, the data stored in any Memory tables is lost. The fact that Memory tables require no disk access, however, makes them blazing fast! Since session data is intended to be volatile anyway, we didn’t really mind if this particular table wouldn’t survive a server restart.

According to the documentation, Memory tables have the same table-level locking weakness as MyISAM. Nevertheless, when we switched our session table to the Memory storage engine, our database server’s CPU usage dropped to virtually zero!

Memory tables have some harsh restrictions that mean they aren’t a cure-all for performance issues. Disappearing data aside, Memory tables cannot contain large column types like TEXT or BLOB. Indeed, the largest piece of data you can store in a Memory table row is a 255 character CHAR or VARCHAR. In our case, we actually had to shorten a couple of our session variable names to make sure they would fit!

At this point, our session table is gliding along happily under moderate load. As the traffic from this article and some other promotion we have planned hits the server, we will be watching closely to decide if the Memory storage engine is up to the task, or if we should switch back to InnoDB to take advantage of row-level locking. In either case, we learned an important lesson: when performance counts, take the time to think about you choice of MySQL storage engine. In our case, it took us from a swamped database server to one showing zero CPU usage.

Related posts:

1. MySQL: the Pros and Cons of InnoDB Tables
2. MySQL Cross-Platform Table Naming
3. MySQL: the Pros and Cons of MyISAM Tables

My recent tutorials received a number of comments complaining about namespace implementation in PHP. The main issues were the syntax and the backslash character. Before I tackle those issues, let’s take a quick look back at the history of PHP.

PHP is a Mess

Languages such as C# and Java were designed and follow rigorous syntax standards. PHP has evolved. The original version was released in 1995 and, by version 3, it was a popular procedural programming language. Version 4 introduced rudimentary object orientation and version 5 provides a reasonably standard OOP model. Namespaces have now been added to version 5.3.

PHP critics will argue that the language is a mess. Function names are inconsistent (e.g. strpos, str_split, substr), object handling has been tagged on, and some of the syntax is different — if not bizarre — when compared with other languages.

However, PHP remains the most widely-used server-side development language. Its versatility is one of its primary strengths:

• Novice developers can start with simple procedural programming. They need never touch OOP techniques and can still be productive.
• Code written 10 years ago in PHP 3 still works today in PHP 5.3. A few minor tweaks may be required, but major rewrites are rarely necessary.

PHP code may not always be pretty, logical, or elegant, but development is rapid and often easier to comprehend than the alternatives.

PHP Namespace Implementation

Unlike C# and Java, PHP has to retain compatibility with non-namespaced code. That has been achieved and you can choose whether to use namespaces or not. However, if you’re using PHP 5.3 (or above), I would recommend them — even if you simply use the same name throughout the whole of your project.

The choice of namespace and use as namespace operators seems logical. Some developers may disagree, but that would have been the case no matter what they’d been named.

Finally, we come to the backslash character. Most critics complain that it’s ugly, difficult to read, and awkward to type on a Mac. However, I still consider it preferable to the double-colon that was originally proposed. Examine the following static method call:

// PHP 5.3 beta static method call
echo ::App::Lib1::MyClass::WhoAmI();

// PHP 5.3 final static method call
echo \App\Lib1\MyClass::WhoAmI();

The second line is quicker to type, less error-prone, easier to read, and simpler to understand. If you see a backslash outside of a string, you know namespacing must be involved.

Of course, it would be great if PHP used a ‘.’ period for public methods, static methods, and namespaces. That would make it consistent with Java, C#, JavaScript, Python and many other languages. Unfortunately, PHP’s history and backwards compatibility makes that difficult to achieve.

No language is perfect, and PHP is far from it! However, namespacing has been implemented well, especially when you consider the restrictions and problems it could have caused. I’m sure you’ll learn to love that backslash!

Related reading:

• How to Use PHP Namespaces, Part 1: The Basics
• How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
• How to Use PHP Namespaces, Part 3: Keywords and Autoloading

Related posts:

1. How to Use PHP Namespaces, Part 1: The Basics
2. How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
3. How to Use PHP Namespaces, Part 3: Keywords and Autoloading

The __NAMESPACE__ Constant

__NAMESPACE__ is a PHP string that always returns the current namespace name. In the global space it will be an empty string.

<?php
namespace App\Lib1;
echo __NAMESPACE__; // outputs: App\Lib1
?>

The value has obvious benefits during debugging. It can also be used to dynamically generate a fully-qualified class name, e.g.

<?php
namespace App\Lib1;

class MyClass {
	public function WhoAmI() {
		return __METHOD__;
	}
}

$c = __NAMESPACE__ . '\\MyClass';
$m = new $c;
echo $m->WhoAmI(); // outputs: App\Lib1\MyClass::WhoAmI
?>

The namespace Keyword

The namespace keyword can be used to explicitly reference an item within the current namespace or a sub-namespace. It is the namespace equivalent of self within classes:

<?php
namespace App\Lib1;

class MyClass {
	public function WhoAmI() {
		return __METHOD__;
	}
}

$m = new namespace\MyClass;
echo $m->WhoAmI(); // outputs: App\Lib1\MyClass::WhoAmI
?>

Autoloading Namespaced Classes

One of the best time-saving features of PHP 5 is autoloading. In global (non-namespaced) PHP code, a standard autoload function could be written:

<?php
$obj1 = new MyClass1(); // classes/MyClass1.php is auto-loaded
$obj2 = new MyClass2(); // classes/MyClass2.php is auto-loaded

// autoload function
function __autoload($class_name) {
	require_once("classes/$class_name.php");
}
?>

In PHP 5.3, you can create an instance of a namespaced class. In that situation, the fully-qualified namespace and class name is passed to the __autoload function, e.g. the value of $class_name could be “App\Lib1\MyClass”. You could continue to place all your PHP class files in the same folder and strip the namespace from the string, however, that could result in file name clashes.

Alternatively, your class file hierarchy could be organized in the same way as your namespace structure. For example, a MyClass.php file could be created in the folder /classes/App/Lib1:

/classes/App/Lib1/MyClass.php:

<?php
namespace App\Lib1;

class MyClass {
	public function WhoAmI() {
		return __METHOD__;
	}
}
?>

A file in root folder could then use the following code:

myapp.php:

<?php
use App\Lib1\MyClass as MC;

$obj = new MC();
echo $obj->WhoAmI();

// autoload function
function __autoload($class) {

	// convert namespace to full file path
	$class = 'classes/' . str_replace('\\', '/', $class) . '.php';
	require_once($class);

}
?>

Explanation:

1. The class App\Lib1\MyClass is aliased as MC.
2. new MC() is translated to new App\Lib1\MyClass() during compilation.
3. The string “App\Lib1\MyClass” is passed to the __autoload function. This replaces all namespace backslashes with file path forward slashes, and modifies the string so the file “classes\App\Lib1\MyClass.php” is loaded.

I hope you found this series of PHP namespace articles useful. Will you be namespacing in your PHP code?

See also:

• How to Use PHP Namespaces, Part 1: The Basics
• How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
• How to Install PHP 5.3 on Windows

Related posts:

1. How to Use PHP Namespaces, Part 1: The Basics
2. How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
3. Are PHP Namespaces Really So Bad?

For the purposes of this example, we will define two almost identical code blocks; the only difference is their namespace:

lib1.php:

<?php
// application library 1
namespace App\Lib1;

const MYCONST = 'App\Lib1\MYCONST';

function MyFunction() {
	return __FUNCTION__;
}

class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

lib2.php:

<?php
// application library 2
namespace App\Lib2;

const MYCONST = 'App\Lib2\MYCONST';

function MyFunction() {
	return __FUNCTION__;
}

class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

There is a little PHP terminology to understand before we begin…

Fully-qualified name
Any PHP code can refer to a fully-qualified name — an identifier starting with the namespace backslash separator, e.g. \App\Lib1\MYCONST, \App\Lib2\MyFunction(), etc.

Fully-qualified names have no ambiguity. The initial backslash operates in a similar way to a file path; it signifies the ‘root’ global space. If we implemented a different MyFunction() in our global space, it could be called from lib1.php or lib2.php using \MyFunction().

Fully-qualified names are useful for one-off function calls or object initialization. However, they can become impractical when you are making lots of calls. As we will discover below, PHP offers other options to save us from namespace typing cramps.

Qualified name
An identifier with at least one namespace separator, e.g. Lib1\MyFunction().

Unqualified name
An identifier without a namespace separator, e.g. MyFunction().

Working Within the Same Namespace

Consider the following code:

myapp1.php:

<?php
namespace App\Lib1;

require_once('lib1.php');
require_once('lib2.php');

header('Content-type: text/plain');
echo MYCONST . "\n";
echo MyFunction() . "\n";
echo MyClass::WhoAmI() . "\n";
?>

Although we include both lib1.php and lib2.php, the identifiers MYCONST, MyFunction, and MyClass will only reference code in lib1.php. This occurs because the myapp1.php code is within the same App\Lib1 namespace:

result:

App\Lib1\MYCONST
App\Lib1\MyFunction
App\Lib1\MyClass::WhoAmI

Namespace Importing

Namespaces can be imported with the use operator, e.g.

myapp2.php:

<?php
use App\Lib2;

require_once('lib1.php');
require_once('lib2.php');

header('Content-type: text/plain');
echo Lib2\MYCONST . "\n";
echo Lib2\MyFunction() . "\n";
echo Lib2\MyClass::WhoAmI() . "\n";
?>

Any number of use statements can be defined or you can separate individual namespaces with a comma. In this example we have imported the App\Lib2 namespace. We still cannot refer directly to MYCONST, MyFunction or MyClass because our code is in the global space and PHP will look for them there. However, if we add a prefix of ‘Lib2\’, they become qualified names; PHP will search through the imported namespaces until it finds a match.

result:

App\Lib2\MYCONST
App\Lib2\MyFunction
App\Lib2\MyClass::WhoAmI

Namespace Aliases

Namespace aliases are perhaps the most useful construct. Aliases allow us to reference long namespaces using a shorter name.

myapp3.php:

<?php
use App\Lib1 as L;
use App\Lib2\MyClass as Obj;

header('Content-type: text/plain');
require_once('lib1.php');
require_once('lib2.php');

echo L\MYCONST . "\n";
echo L\MyFunction() . "\n";
echo L\MyClass::WhoAmI() . "\n";
echo Obj::WhoAmI() . "\n";
?>

The first use statement defines App\Lib1 as ‘L’. Any qualified names using ‘L’ will be translated to ‘App\Lib1′ at compile-time. We can therefore refer to L\MYCONST and L\MyFunction rather than the fully-qualified name.

The second use statement is more interesting. It defines ‘Obj’ as an alias for the class ‘MyClass’ within the App\Lib2\ namespace. This is only possible for classes — not constants or functions. We can now use new Obj() or run static methods as shown above.

result:

App\Lib1\MYCONST
App\Lib1\MyFunction
App\Lib1\MyClass::WhoAmI
App\Lib2\MyClass::WhoAmI

PHP Name Resolution Rules

PHP identifier names are resolved using the following namespace rules. Refer to the PHP manual for more information.

1. Calls to fully-qualified functions, classes or constants are resolved at compile-time.

2. Unqualified and qualified names are translated according to the import rules, e.g. if the namespace A\B\C is imported as C, a call to C\D\e() is translated to A\B\C\D\e().

3. Inside a namespace, all qualified names not already translated according to import rules have the current namespace prepended, e.g. if a call to C\D\e() is performed within namespace A\B, it is translated to A\B\C\D\e().

4. Unqualified class names are translated according to current import rules and the full name is substituted for short imported name, e.g. if class C in namespace A\B is imported as X, new X() is translated to new A\B\C().

5. Unqualified function calls within a namespace are resolved at run-time. For example, if MyFunction() is called within namespace A\B, PHP first looks for the function \A\B\MyFunction(). If that is not found, it looks for \MyFunction() in the global space.

6. Calls to unqualified or qualified class names are resolved at run-time. For example, if we call new C() within namespace A\B, PHP will look for the class A\B\C. If that is not found, it will attempt to autoload A\B\C.

See also:

• How to Use PHP Namespaces, Part 1: The Basics
• How to Use PHP Namespaces, Part 3: Keywords and Autoloading
• How to Install PHP 5.3 on Windows

In tomorrow’s final article we will cover autoloading and other advanced options.

Related posts:

1. How to Use PHP Namespaces, Part 1: The Basics
2. How to Use PHP Namespaces, Part 3: Keywords and Autoloading
3. Are PHP Namespaces Really So Bad?

Why Do We Need Namespaces?

As the size of your PHP code library increases, there is increased risk of accidentally re-defining a function or class name that has been declared before. The problem is exacerbated when you attempt to add third-party components or plugins; what if two or more code sets implement a ‘Database’ or ‘User’ class?

Until now, the only solution has been long class/function names. For example, WordPress prefixes every name with ‘WP_’. The Zend Framework uses a highly descriptive naming convention that results in long-winded class names such as Zend_Search_Lucene_Analysis_Analyzer_Common_Text_CaseInsensitive.

Name collision problems can be solved with namespaces. PHP constants, classes, and functions can be grouped into namespaced libraries.

How are Namespaces Defined?

By default, all constant, class, and function names are placed in the global space — like they were before PHP supported namespaces.

Namespaced code is defined using a single namespace keyword at the top of your PHP file. It must be the first command (with the exception of declare) and no non-PHP code, HTML, or white-space can precede the command, e.g.

<?php
// define this code in the 'MyProject' namespace
namespace MyProject;

// ... code ...

The code following this line will be assigned to the ‘MyProject’ namespace. It is not possible to nest namespaces or define more than one namespace for the same code block (only the last will be recognized). However, you can define different namespaced code in the same file, e.g.

<?php
namespace MyProject1;
// PHP code for the MyProject1 namespace

namespace MyProject2;
// PHP code for the MyProject2 namespace

// Alternative syntax
namespace MyProject3 {
	// PHP code for the MyProject3 namespace
}
?>

Although this is possible, I would advise against it: retain your sanity by defining a single namespace per file.

Sub-namespaces
PHP allows you to define a hierarchy of namespaces so libraries can be sub-divided. Sub-namespaces are separated using a backslash (\) character, e.g.

• MyProject\SubName
• MyProject\Database\MySQL
• CompanyName\MyProject\Library\Common\Widget1

Calling Namespaced Code

In a file named lib1.php, we will define a constant, a function, and a class within the App\Lib1 namespace:

lib1.php

<?php
// application library 1
namespace App\Lib1;

const MYCONST = 'App\Lib1\MYCONST';

function MyFunction() {
	return __FUNCTION__;
}

class MyClass {
	static function WhoAmI() {
		return __METHOD__;
	}
}
?>

We can now include this code in another PHP file, e.g.

myapp.php

<?php
header('Content-type: text/plain');
require_once('lib1.php');

echo \App\Lib1\MYCONST . "\n";
echo \App\Lib1\MyFunction() . "\n";
echo \App\Lib1\MyClass::WhoAmI() . "\n";
?>

No namespace is defined in myapp.php so the code exists in the global space. Any direct reference to MYCONST, MyFunction or MyClass will fail because they exist in the App\Lib1 namespace. To call code in lib1.php, we can add a prefix of \App\Lib1 to define fully-qualified names. The following result is output when we load myapp.php:

App\Lib1\MYCONST
App\Lib1\MyFunction
App\Lib1\MyClass::WhoAmI

Fully-qualified names can become quite long and there are few obvious benefits over defining long class names such as App-Lib1-MyClass. Therefore, in the next article, we will discuss aliasing and take a closer look at how PHP resolves namespace names.

See also:

• How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
• How to Use PHP Namespaces, Part 3: Keywords and Autoloading
• How to Install PHP 5.3 on Windows

Related posts:

1. How to Use PHP Namespaces, Part 2: Importing, Aliases, and Name Resolution
2. How to Use PHP Namespaces, Part 3: Keywords and Autoloading
3. Are PHP Namespaces Really So Bad?