a programmer's best friend :: the blog of pat, the dog

I just made a bugfix release of the patTemplate 3.0.x branch, which fixes some small notices and bugs that have been reported in the last few months. If you are using patTemplate 3.0.0 I recommend you to upgrade.
If you would like to test some of the new features I have added to patTemplate you may grab the latest snapshot of the 3.1.x series from snap.php-tools.net.

I finally managed to release a first public beta of my configuration reader patConfiguration.
Starting with this release it is now driver-based which keeps the codebase small and at the same time allows you to read and write XML, INI and WDDX files using the same API. The XML-reader is the most powerful driver as it allows you to define how you would like the tags to be handled. This means you can define that the tag <foo one="1" bar="totmato"/> should automatically be converted to an array that should contain the attributes of the tag as values. Of course you can also choose which types to use for the attribute values, so they get converted to booleans, floats, integers, strings, arrays or objects.
To achieve this, patConfiguration provides a very easy-to-use built-in tag:
<!-- define a new namespace -->
<define ns="shop">
    <!-- define a tag in the namespace -->
    <define tag="articles" type="array"/>

    <!-- Define a tag with no name (indexed array) -->
    <define tag="article" name="_none" type="array">
        <!-- define three attributes for this tag -->
        <define attribute="vendor" type="string"/>
        <define attribute="title" type="string"/>
        <define attribute="price" type="float" default="99.99"/>
    </define>
</define>
Now that you've defined, how patConfiguration should interpret the tags, you may use them in your configuration:
<shop:articles>
    <shop:article title="Power battery" vendor="Green Lantern"/>
    <shop:article title="Batarang" vendor="Batman" price="500"/>
</shop:articles>
Parsing this configuration is extremely easy:
<?php
$conf = new patConfiguration(
                            array(
                                'configDir' => './config'
                                )
                            );
// parse config file
$conf->loadConfig('example_define_basic.xml');

$config = $conf->getConfigValue('articles');
?>
If you worry about the overhead of parsing XML files on every request, you may want to switch-on the caching system which makes loading the configuration faster then reading it from PHP files. If you want to use your tag definitions in more than one file, just use external entities or xInclude tags, patConfiguration supports both, even in PHP4.
After reading this XML-document with patConfiguration, you'll get the following array structure back:
Array
(
    [0] => Array
        (
            [vendor] => Green Lantern
            [title] => Power battery
            [price] => 99.99
         )

    [1] => Array
        (
            [vendor] => Batman
            [title] => Batarang
            [price] => 500
         )
)
patConfiguration allows you to return the complete configuration or only parts of it, using a mixture of PHP's array snytax and a path to the desired value. If you'd like to see more features of patConfiguration in action, you may want to take a look at the online examples or download it from our site.
If you are using PEAR 1.4.0 you may also get it from our PEAR-channel:
$ pear channel-discover pear.php-tools.net
$ pear install --alldeps pat/patConfiguration
If you stumble upon a bug, please report it using our bugtracker.

Our new member Daniel Wiegand (wiegi) implemented a PEAR compatible client for Yahoo's new REST-based webservice API. From the Yahoo developer site: "Yahoo! Search Web Services allow you to access Yahoo content and services in your favorite programming languages. This means you can now build Yahoo directly into your own applications." By using Daniel's PHP5 client you do not need to worry about the protocol or the resulting XML format, everything is done in plain PHP:
<?PHP
$yahoo = new Services_Yahoo($appId);
try {
    // do a simple search
    $result = $yahoo->searchWeb('PEAR');
    
    echo "Total results returned: " . $result->getTotal() . "<br />\n";
    
    foreach ($result as $entry) {
        
        printf('<a href="%s">%s</a><br />', $entry['ClickUrl'], $entry['Title']);
        printf('<i>%s</i><br /><br />', $entry['Summary']);
    }        
} catch (Services_Yahoo_Exception $e){
    echo $e;
}
?>
Besides searchWeb() the client provides more methods to use the different web services offered by Yahoo:

• searchImages()
• searchVideos()
• searchNews
• searchLocal()

Each of the methods can be used with several parameters that need to be passed in a fixed parameter order or you may pass a associative array that contains any parameters you want to pass.
As Daniel has been using PHP5 all of these methods return a Services_Yahoo_Result object that provides methods to return the total number of search results but can be iterated like a normal object, thanks to SPL. This result object offers a lot more, as you can use it to fetch the next page using the same search parameters:
<?PHP
$yahoo = new Services_Yahoo($appId);
try {
    // do a simple search
    $result = $yahoo->searchWeb('Graceland');
    
    printf("Total results returned: %d<br />\n", $result->getTotal());
    printf("Fetching %d entries starting from %d.<br />\n", $result->getReturned(), $result->getCurrent());
    
    foreach ($result as $entry) {
        
        printf('<a href="%s">%s</a><br />', $entry['ClickUrl'], $entry['Title']);
        printf('<i>%s</i><br /><br />', $entry['Summary']);
    }
    
    echo "Test, whether more entries are available....<br /><br />\n";
    if ($result->hasNext()) {
        $result->fetchNext();
    }
    
    printf("Fetching %d entries starting from %d.<br />\n", $result->getReturned(), $result->getCurrent());
    
    foreach ($result as $entry) {
        
        printf('<a href="%s">%s</a><br />', $entry['ClickUrl'], $entry['Title']);
        printf('<i>%s</i><br /><br />', $entry['Summary']);
    }
    
} catch (Services_Yahoo_Exception $e){
    echo $e;
}
?>Quite cool, isn't it?
You can take a loot at the sources at http://pear.php-tools.net/projects/Services_Yahoo/ or even download a PEAR installable package from http://pear.php-tools.net/projects/Services_Yahoo/Services_Yahoo-0.1.0.tgz (requires PHP5, XML_Serializer and HTTP_Request).

We would have loved to propose this to PEAR, but there already is a draft for a Services_Yahoo package by Martin Jansen, but until now he hasn't showed any of his code. Hopefully Daniel and Martin could be working on a package together.

I really do! Yesterday he released the first official version of PEAR 1.4.0 (alpha, of course) which provides a lot of new features. The most interesting feature is the ability to install files from different channels, which is really great for our non-PEAR packages at php-tools.net. But that's not all, Greg did to get my love: He also developed a PEAR_Server with a simple HTML frontend that can be easily installed using PEAR 1.4.0. So this morning I decided to play with it a bit and after several minutes, I had our own channel server online which is already able to serve patError and patTemplate (more projects will follow). If you'd like to try it, download PEAR 1.4.0a2 and then add our channel and start installing the packages:
pear upgrade PEAR-alpha
pear channel-discover pear.php-tools.net
pear install pat/patTemplate

If your are interested in documentation and technical insight, the following postings might be of interest to you:
Several PEAR-related posts in Greg's blog
A look at package2.xml and how to create a PEAR 1.4 package by Tobias Schlitt
Set up you own PEAR channel by Tobias Schlitt

I'll keep you updated on our new channel server. And once more:

Thanks Greg, you've done the most amazing job I can imagine.

Yesterday a new devleoper joined patPortal, by committing a new Response Filter to the project. patPortal is a component-based and event-driven framework that uses an extremly high level of abstraction, as you never access any session, GET or POST directly directly, but use a request object for this. This allows us to use the same API for HTTP-based applications as well as SOAP requests et al.
The same principle is used for the response, as you are never sending data directly to the client but pass it to a reponse object instead. Daniel's response filter now allows you to strip unnecessary whitespace from the response prior to sending it to the client.
Daniel decided to join us for this project, so welcome aboard the pat-team. You can reach him at wiegi[at]php-tools[dot]net.

I just released a new version of Services_Ebay, which provides two cool new features, as well as several new API-calls. On of the new features is the new caching system, I added to the model classes. As API calls to the eBay API tend to be quite time consuming (and expensive) most users probably will be trying to cache the return values from the eBay API. So I decided to add this as an optional feature to Services_Ebay. Using the cache is extremely easy:
<?php
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);

// build a filesystem cache
$userCache = Services_Ebay::loadCache('Filesystem', array('path' => './cache'));

// use a static expiry of 15 minutes
$userCache->setExpiry('Static', 15);

// use this cache for all user models
Services_Ebay_Model_User::setCache($userCache);

// load a new user model
$user = Services_Ebay::loadModel('User', 'superman-74', $session);

if ($user->isCached()) {
echo 'data had been cached';
print_r($user->toArray());
} else {
echo 'fetching user data from eBay';
$user->Get();

print_r($user->toArray());
}
?>
After instantiating a new cache container, you set the type of expiry you want to use for caching the data. Currently only a fixed expiry time is supported, but this can be changed easily (as expiry checks are objects) and thus an expiry check will be added that caches data of eBay items shorter the nearer the end of the auction draws. I'll probably also add cache containers based on databases, as the are more flexible than filesystem caches.

The second feature I added (with some help by the fabulous Adam Trachtenberg) is the support for product finders. Product finders are those neat and advanced forms that eBay provides on their website, which lets you choose the style, color, size of clothing or any other item you are looking for. eBay's API provides to calls that help you adding those interactive search tools to your site as well: GetProductFinder, which returns XML code with the raw information (form elements and values for a certain category) and GetProductFinderXSL which returns the stylesheet eBay uses to render the HTML from the raw XML data. Services_Ebay makes working with these calls extremely easy, as it provides a ProductFinder model:
<?php
$session = Services_Ebay::getSession($devId, $appId, $certId);
$session->setToken($token);
$ebay = new Services_Ebay($session);

// load the product finder XSL, fetching it everytime as too expensive
$xsl = file_get_contents('product_finder.xsl');

// get product finder
list($productFinder) = $ebay->GetProductFinder(1909);
echo $productFinder->render($xsl);
}
?>
Using this code will result in 4 drop-down menus as well as some javascript, which will update them, whenever the user selects an item.

The new release is also the first release which features code by Carsten Lucke, who added two new API calls (that deal with Dutch auctions and member messages) as well as the needed models for these calls.

Adam Trachtenberg, manager of Technical Evangelism at eBay, has written an introductory tutorial on Services_Ebay, one of my newest PEAR packages.
Although this ONLamp.com tutorial is rather short, it deals with some interesting aspects of Services_Ebay, as he shows what can be accomplished by object-overloading and he even makes use of the ability to switch model classes in a way I've never thought of them. Adam implements his own models to use them as a presentation layer as he only changes the output of the __toString() method.
If you are interested in the Services_Ebay package, this is the tutorial that will get you started.

I will be giving two talks at the annual PHP Conference in Amsterdam this year:

1. Go OO! - Real-life patterns in PHP5
   This talk will show you how to use PHP5's new object-oriented capabilities and the interfaces of SPL
2. Component and event-driven architectures in PHP5
   This session will introduce you to new concepts of web development and show you how to implement event handling in your applications which make them a lot more flexible

In addition to these sessions I'll be doing a power workshop entitled "XML and Web services with PHP5 and PEAR" together with Tobias Schlitt.

Hope to see you there!

Bertrand Mansion started a new proposal for Event_Dispatcher, a package that provides easy-to-use event handling for your projects. I only realized that this package has been proposed as Betrand started the call for votes on this package, but as I'm using this technique a lot in patPortal and at my work, I decided to give this package a try.

The package's architecture is quite simple: There is an Event_Dispatcher, which is able to hold observers (native PHP callbacks) for different notification types. These observers will be notified whenever an event (aka notification) occurs. This notification is a simple object that stores information about the event itself. In real life you can use it to add functionality to your sites, without having to change the code of your application, e.g. in my applications, I send a notification,whenever a user places an order (onOrder) and pass the order object to the notification. This way I can easily plug in new objects, that write logfiles, update cookies or send a trackback to an affiliate partner.

As I liked the simple architecture of the package, I played with it a little and reached some limits of the package as it has been missing features I heavily use in my commercial projects. Thi first feature I was missing was the ability to let an observer cancel the notification (for example if you want to plugin in some checks before a user is able to place an order, which enable you to cancel an order after the user pressed the submit button), so I added this to Bertrand's code.
Next was the ability for event bubbling, which allows you unlimited levels of event handling and an event that was triggered at a lower level will then inform all observers of the higher levels. So I added this feature as well, by allowing the user to nest as many dispatchers as they like.
And last but not least, I wanted to be able to use a custom class for notifications, which is now possible in my version as well (for a single dispatcher as well as all dispatchers).

I hope that Bertrand will include all these changes in the official distribution and that this package will be accepted by the PEAR community, so if you haven't voted, do it now.

I just released a new version of HTTP_SessionServer, a daemon that is able to store key value pairs and communicates with any kind of client using a simple protocol.
Besides some cosmetic changes, this release features a new backend contributed by Carsten Lucke, which stores session data in a database using the DB abstraction layer.

If you'd like to learn more about how HTTP_SessionServer works, you can take a look at the presentation I did at the International PHP Conference in Frankfurt.

I released new versions of two of my PEAR packages: XML_Parser 1.2.2 and XML_Serializer 0.14.0. While XML_Parser 1.2.2 only fixes two bugs, XML_Serializer 0.14.0 provides two cool new features:

1. By splitting the SAX-handlers from the XML_Parser class (which is possible since XML_Parser 1.2.0) you may now set the source and the target encoding of the XML documents that you want to unserialize. This enables you to read UTF-8 encoded documents and convert them to ISO-8859-1 on-the-fly.
2. I added a new option "encodeFunction" to the XML_Serializer class, which lets you specify a PHP function or method that will be called for all character data and attributes before they are written to the XML document. This allows you to encode your data in UTF-8 before creating an XML-document. As XML_Unserializer provides a matching option to decode the data, you could also use this to transparently encrypt XML and decrypt XML documents

I added these two new features, as eBay requires applications to work with UTF-8 encoded XML documents and thus Services_Ebay needs to read and write UTF-8 encoded XML-streams. But the more I think about these features the more situations come to my mind where those options could be timesavers.