Services_Blogging

Generic driver-based package to post and read blog entries.

Introduction to Services_Blogging

Weblogs are an important part of the internet: They allow normal people to express their opinions and thoughts to their family, friends and the whole world by simply publishing some text on a server. This process is very easy and you don't need a grade in computer science to even host a blog on your own or a rented server.

One drawback of blog software is mostly their user interface: Since it is browser based, it requires you to be either online all the time while writing your blog post, or write it in a normal text editor and copy&paste it when going online. Using a text editor you cannot apply font styles to your text.. An offline tool to write blog entries would be really nice in this case.

Considering the idea of an offline tool for writing blog entries leads to the availability of access to your blog from outside the normal web interface - e.g via web services. Most blog hosters and blogging software packages have support for such a web services API, mostly via XML-RPC.

Unfortunately, there are many different of these application programming interfaces in the wild. Some of them support only posting of blog entries, other ones also allow reading. Some blog softwares support images and tags in their posts, others not. The variety is large, and so you could end up writing custom code for every blog server you want to access because of the differences in their API.

This is the point at which Services_Blogging comes into play: It provides a unified API to post and read blog entries, independent of the API supported by the server software hosting the blog. It uses a driver-based approach to communicate with different APIs out there. If a new blogging API is invented, someone just needs to write a driver for the Services_Blogging package, and everyone can access also this blogs.

As of April 2007, the package has the following drivers:

Blogger
LiveJournal
MetaWeblog

Connecting your blog server

To post entries to your blog, you first need to obtain an instance of the Services_Blogging_Driver suitable for your blog. You need to either find out which API your blog system supports, or let Services_Blogging magically autodiscover those settings.

Creating a driver is done using Services_Blogging's factory() method. It requires five parameters: The driver name, username, password, server URL and the path of the API on the server.

Example 67-1. Instantiating a driver using Services_Blogging::factory()

require_once 'Services/Blogging.php';
$bl = Services_Blogging::factory(
    'metaWeblog', //driver name
    'username',
    'password',
    'http://blog.example.com',
    '/xmlrpc.php'
);

Some blog drivers don't need server and path variables, just fill in null in this case.

Autodiscovering settings

Since it can be tedious to find out which settings are needed for your own blog, this package has a feature called autodiscovery. You either can automatically detect the settings needed to create an instance of the driver needed, or let the class automatically detect and return an instance of the driver needed for your blog system.

Autodiscovering the settings of your blog can be done via Services_Blogging's discoverSettings(), passing the URL of your blog as only parameter. It returns an array with all the needed settings.

Most of the blogging softwares today support multiple blogging APIs. After getting a list of supported APIs via autodiscovery, you need to choose which one fits you best; it's usually the one supporting the most features. Services_Blogging also helps you with this task by providing a method called getBestAvailableDriver(), just passing the array of recently discovered settings to it. Now you have all data needed to instantiate the driver itself.

Example 67-2. Auto-discovering settings

require_once 'Services/Blogging.php';

$settings = Services_Blogging::discoverSettings('http://blog.example.com');
var_dump($settings);
echo Services_Blogging::getBestAvailableDriver($settings) . "\r\n";
//go on with factory()

If that all is still too much work for you, you can let do Services_Blogging everything by calling discoverDriver(), passing the URL of your blog, your username and password to it. It returns a the driver object.

Example 67-3. Creating a driver automatically

require_once 'Services/Blogging.php';

$bl = Services_Blogging::discoverDriver(
    'http://blog.example.com',
    'username',
    'password'
);

Note: The autodiscovery methods throw an exception of type Services_Blogging_Exception if something goes wrong (either autodiscovery fails because your blog software does not support it, or there is no suitable driver for your blog).

Drivers

Due to the difference of features in the existing blogging APIs, there are two driver classes: Services_Blogging_Driver and Services_Blogging_ExtendetDriver (which extends the first).

Drivers extending Services_Blogging_Driver do only support creating, saving and deleting posts. They are not able to list (or modify) existing posts.

Drivers extending from Services_Blogging_ExtendetDriver do have more features: Reading existing posts, get a list of recent posts, and getting a list of the titles of the recent posts.

Blog posts / entries

Beside the difference in features regarding reading and listing existing posts, the APIs have different support for blog post properties. While some simple APIs only allow to define the text of a post, better ones allow to set the title and other ones also support extendet properties like date, date to publish, categories and other.

Once you have the driver object for your blog, you should get a list of post properties supported by your driver. The method is getSupportedPostProperties(); it returns an array of property names. Currently, the following properties are possible:

title
content
publishdate
date
url
categories

See the API documentation of Services_Blogging_Post for the data types.

Example

Example 67-4. Posting an entry

<?php
require_once 'Services/Blogging.php';

$bl = Services_Blogging::factory(
    'metaWeblog',
    'username', 'password',
    'http://blog.example.com', '/xmlrpc.php'
);


$post = $bl->createNewPost();
//$post->setId('14');
$post->title = 'Modified post title';
$post->content = "This is a modified test post by"
               . " Services_Blogging\r\n\r\nSecond line\r\nThird one";
$post->categories = array('cat1', 'cat3');

$bl->savePost($post);
$nLastPostId = $post->id;
echo 'post id: ' . $nLastPostId . "\r\n";

//$bl->deletePost(17);

var_dump($bl->getPost($nLastPostId));
var_dump($bl->getRecentPostTitles(2));
var_dump($bl->getRecentPosts());

?>