SIOC/PHPExportAPI
About
The PHP Export API provides an easy way for developers to create SIOC exporters, as it maps SIOC Classes to PHP objects, with simple functions to export the created data. In this way it enables developers to create SIOC export tools without the need to get into technical details about how information is represented in RDF/XML – they are operating at the level of SIOC concepts instead. Thus, developers only have to deal with extracting content from their weblog databases and then passing it to the API that will render SIOC data.
When using the API for your exporter, you won't have to deal with SIOC specs or RDF formatting, and you could easily update your exporter to the latest version of SIOC specifications by simply updating the API file in your exporter. The SIOC PHP API is already being used by SIOC export plugins for the export plugins for DotClear, b2evolution and vBulletin.
Currently the API supports SIOC v.1.08
General Information
The API consists of PHP5 file (compatible to PHP4), called sioc_inc.php, that can be downloaded from SVN here. There are 2 main classes in the API:
* SIOCExporter, which is the exporter itself; * SIOCObject, a generic SIOC Class, from which all real SIOC Class inherits (eg: SIOCPost ...)
More generally, it is a good practice to have a URL for the sioc export, then parameters that will define if you're exporting the site, a forum, a UserAccount or a Post, an another parameter referring to the ID of the exported class, as current exporter do.
All the examples of this tutorial are from DotClear exporter, that can be downloaded here
The SIOC API creates and exports SIOC concepts from the blog: authors (sioc:UserAccount plus foaf:Person), posts and comments (sioc:Post) and the structure of the blog (sioc:Site plus sioc:Forum). While a regular weblog contains only a single blog (represented in SIOC as a sioc:Forum) the Site/Forum architecture allows us to describe the structure of all weblogs and online community sites in a uniform way, e.g., multi-user blog sites such as wordpress.com can be represented as a Site with multiple Forums (blogs).
SIOCExporter Class
Basic exporter usage is:
* Create a SIOCExporter and set its parameters * Add it some SIOC Classes instances * Export data in RDF
Eg:
{{{ $ex = new SIOCExporter(); $ex->setParameters(dc_blog_name, $blog_url, $sioc_url, dc_encoding, PLUGIN_URL . "/#" . PLUGIN_VERSION); $ex->addObject($object); $ex->export(); }}}
where $object is a Post, User ... (see next section)
The function setParameters($title, $url, $sioc_url, $encoding, $generator) must be called with the following parameters:
* $title : The title of your website / blog * $url : The URL of you website / blog * $sioc_url : URL of its SIOC export (without additionnal parameters) * $encoding : Output encoding * $generator : The URL of your exporter plugin (so that people know where to look for additional exporter information)
The function setURLParameters($type='type', $id='id', $page='page', $url_usetype = true, $urlseparator='&', $urlequal='=', $suffix=\'\') can be optionnaly called in order to define type the of SIOC URLs.
Eg, for a Post export based on sioc.php page:
* default URLparameters (for a post) => sioc.php?type=post&post_id=xx * setURLParameters('type', 'id', 'page', 'false') => sioc.php?type=post&id=xx * setURLParameters('sioc_type', 'sioc_id', 'page', 'false') => sioc.php?sioc_type=post&sioc_id=xx * setURLParameters(, , 'p', 'false', '/') => sioc.php/data/p/xx
Other methods associated to SIOCExporter are:
* setURLTypeParm * setSuffixIgnore * siocURL
SIOCObject Class
SIOCObject is a virtual class that is not designed to be instanciated, but is a base to SIOC / PHP Classes: Site, Forum, Post and User.
The function addNote($note) can be used to append notes to any SIOCObject which will be exported as a rdfs:comment.
Here are the different PHP classes and methods associated to SIOC Classes and properties
SIOCSite Class
SIOCSite($url, $name, $description) :
* $url : URL of sioc:Site * $name : Name of the sioc:Site * $description : A short description of the sioc:Site
function addForum($id, $url) :
* $id : ID of the sioc:Forum * $url : URL of the sioc:Forum (HTML page) * NB: You can add as many forums as needed
function addUser($id, $url) :
* $id : ID of the sioc:UserAccount * $url : URL of the UserAccount (HTML page) * NB: You can add as many users as needed * NB: This method will create a sioc:Usergroup
Eg :
{{{
$site = new SIOCSite($blog_url, dc_blog_name, dc_blog_desc ); $site->addForum(1, $blog_url); if ($authors = $blog->getUser()) { while($authors->fetch()) { $site->addUser($authors->f('user_id'), author_uri($authors->f('user_id'))); } } return $site;
}}}
SIOCForum Class
SIOCForum($id, $url, $page, $title=, $descr=) :
* $id : ID of the sioc:Forum (same as before for a given forum) * $url : URL of the forum (HTML page) * $page : Forums can be paginated (as they have a lot of sioc:Post), this parameter is the current page * $title : Title of the sioc:Forum * $descr : Short description of the sioc:Forum
function addPost($id, $url) :
* $id : ID of the sioc:Post * $url : URL of the Post (HTML) * NB: You can add as many posts as needed
function setNextPage($next) :
* $next : Next page number * NB : Use it only if there's another page that displays the posts
Eg :
{{{
define('PER_PAGE', '10') $forum = new SIOCForum('1', $blog_url, $page ); while($posts->fetch()) { $forum->addPost($posts->f('post_id'), $posts->getPermURL()); } $size = $con->select("SELECT COUNT(post_id) as sum FROM " . $blog->t_post ." WHERE post_pub = 1"); if(($start+PER_PAGE) < (integer)$size->f(0)) { $forum->setNextPage(true); } return $forum;
}}}
SIOCUser Class
Note that User was recently deprecated in favour of UserAccount, but this function name remains the same.
SIOCUser($id, $uri, $name, $email, $homepage=, $foaf_uri=, $role=false) :
* $id : ID of the user (mostly a nick, will be rendered as sioc:name) * $uri : URI of the SIOC node of the sioc:UserAccount * $name : name of the user (complete name, will be rendered as foaf:name) * $email : email of the user * $homepage : homepage of the user * $foaf_uri : URI of the FOAF node of the foaf:Person. Currently, the API creates a siple foaf profile so you can define an internal foaf URI, see example below and here * $role : Role of the UserAccount (currently the sioc:name corresponding to the sioc:Role)
Eg : {{{
$fname = $user->f('user_prenom'); $lname = $user->f('user_nom'); $nick = $user->f('user_pseudo'); $name = ($fname && $lname) ? "$fname $lname" : ($fname ? $fname : ($lname ? $lname : )); $user = new SIOCUser($user->f('user_id'), author_uri($user->f('user_id')), $name, $user->f('user_email'), htmlspecialchars($blog_url), foaf_uri($user->f('user_id')), $user_level ); return $user;
// Creates an internal SIOC URI for the User function author_uri($user) { global $blog_url; return htmlspecialchars($blog_url) . '#' . $user; }
// Creates an internal FOAF URI for the User function foaf_uri($user) { global $blog_url; return htmlspecialchars($blog_url) . '#foaf_' . $user; }
}}}
SIOCPost Class
SIOCPost($url, $subject, $content, $encoded, $creator, $created, $updated="", $topics=array(), $links=array()) :
* $url : URL of the sioc:Post (HTML) * $subject : Subject of the sioc:Post (i.e. its title) * $content : Content of the sioc:Post (plain-text) * $encoded : HTML content of the sioc:Post * $creator : Creator of the sioc:Post /!\ Must be an instance of SIOCUser, not a string * $created : Creation date of the sioc:Post * $updated : Update date of the sioc:Post * $topic : Array of topics of the sioc:Post (see below) * $links : Array of links extracted from the sioc:Post (see below) * NB: regarding $topic and $links, the array have URL as a key, a text description as a value (eg : key = "http://apassant.net/blog/tag/sioc", value = "sioc"
function addComment($id, $url) :
* $id : ID of the sioc:Post which is a comment of the current Post (the API does not yet use sioc Types module) * $url : URL of the Comment (HTML) * NB: You can add as many comments as needed * NB: When creating a comment, as you need to use a real SIOCUser for its $creator, you can mention only its name / homepage properties, the comment will be linked to a foaf:Person profile using foaf:maker, eg: http://apassant.net/blog/sioc.php?type=comment&comment_id=6820
function addReplyOf($id, $url) :
* $id : ID of the sioc:Post which this post comments * $url : URL of the original post (HTML) * NB: This method should be used only for posts that are replies of others
Eg (post, not comment) : {{{
$post = $blog->getPostByID($post_id); if($post->f('pub_mode')) exit();
$topics[$post->getCatURL()] = $post->f('cat_libelle'); if($tag_plugin) { $metatags = twPostMeta::get($post_id, 'tag'); foreach(twPostMeta::get($post_id, 'tag') as $tag) { $topics['http://'.$_SERVER['HTTP_HOST'].twTags::_url($tag)] = $tag; } } $links = extract_wiki_links($post->f('post_content_wiki')); $spost = new SIOCPost($post->getPermURL(), $post->f('post_titre'), $blog->toXML(strip_tags($post->f('post_content'))), $post->f('post_content'), sioc_user($post->f('user_id')), $post->f('post_creadt'), $post->f('post_upddt'), $topics, $links ); // Liste des commentaires et trackbacks $comments = $blog->getComments($post_id); if(!$comments->isEmpty()) { while($comments->fetch()) { if($comments->f('comment_pub')) { $id = $comments->f('comment_id'); $url = $post->getPermURL(). "#c$id"; $spost->addComment($id, $url); } } }
}}}
ToDo
* Documentation in code itself * Submit to PEAR (?) * Allow external FOAF profiles * Allow API to output N3/turtle * What about sioc:topic VS sioc:subject (http://groups.google.com/group/sioc-dev/browse_thread/thread/6d8b7c7fdcd95acc) * Do not display properties if their value is not set Template:Review
Improvements:
* Allow to export a number of objects in the same exporter - e.g., a page containing both a sioc:Site and sioc:Forum. Or a number of sioc:Posts. * Allow to specify an array of links for a SIOCForum as well as for a SIOCPost (e.g., for blogrolls)
Fixed in http://sw.deri.org/svn/sw/2005/08/sioc/php_api/ :
* Do not display a sioc:Usergroup if no authors are defined * Double-escaped & bug * Bug with user email/sha1 not being exported * Missing /> in rdfs:seeAlso's to comments (in SIOCPost)