SIOC/PHPExportAPI

From W3C Wiki

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)
Retrieved from "https://www.w3.org/wiki/index.php?title=SIOC/PHPExportAPI&oldid=98454"