When using the API for you exporters, you won't have to deal with SIOC specs or RDF formatting, and you could easilly update your exporter to the latest version of SIOC specifications by simply updating the API file in your exporter.

Current API supports SIOC v.1.08 It is used in DotClear and b2evo exporters. 

The API consists in a PHP4 file, 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 User 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

SIOCExporter Class

Basic exporter usage is:

1. Create a SIOCExporter and set its parameters
2. Add it some SIOC Classes instances
3. Export data in RDF

Eg:

1. $ex = new SIOCExporter();
2. $ex->setParameters(dc_blog_name, $blog_url, $sioc_url, dc_encoding, PLUGIN_URL . "/#" . PLUGIN_VERSION);
3. $ex->addObject($object);
4. $ex->export();
5. 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:

1. $title : The title of your website / blog
2. $url : The URL of you website / blog
3. $sioc_url : URL of its SIOC export (without additionnal parameters)
4. $encoding : Output encoding
5. $generator : The URL of your exporter plugin (so that people know where to look for additional exporter information)
6. 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:

1. default (for a post) => sioc.php?type=post&post_id=xx
2. setParameters('type', 'id', 'page', 'false') => sioc.php?type=post&id=xx
3. setParameters(, , 'p', 'false', '/') => sioc.php/data/p/xx
4. Other methods associated to SIOCExporter are:
5. setURLTypeParm
6. setSuffixIgnore
7. siocURL
8. 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.

Here are the different PHP classes and methods associated to SIOC Classes and properties

SIOCSite Class

SIOCSite($url, $name, $description) :

1. $url : URL of sioc:Site
2. $name : Name of the sioc:Site
3. $description : A short description of the sioc:Site
4. function addForum($id, $url) :
5. $id : ID of the sioc:Forum
6. $url : URL of the sioc:Forum (HTML page)
7. NB: You can add as many forums as needed
8. function addUser($id, $url) :
9. $id : ID of the sioc:User
10. $url : URL of the User (HTML page)
11. NB: You can add as many users as needed
12. 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=) :

1. $id : ID of the sioc:Forum (same as before for a given forum)
2. $url : URL of the forum (HTML page)
3. $page : Forums can be paginated (as they have a lot of sioc:Post), this parameter is the current page
4. $title : Title of the sioc:Forum
5. $descr : Short description of the sioc:Forum
6. function addPost($id, $url) :
7. $id : ID of the sioc:Post
8. $url : URL of the Post (HTML)
9. NB: You can add as many posts as needed
10. function setNextPage($next) :
11. $next : Next page number
12. 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

SIOCUser($id, $uri, $name, $email, $homepage=, $foaf_uri=, $role=false) :

1. $id : ID of the user (mostly a nick, will be rendered as sioc:name)
2. $uri : URI of the SIOC node of the sioc:User
3. $name : name of the user (complete name, will be rendered as foaf:name)
4. $email : email of the user
5. $homepage : homepage of the user
6. $foaf_uri : URI of the FOAF node of the foaf:User. Currently, the API creates a siple foaf profile so you can define an internal foaf URI, see example below and here
7. $role : Role of the User (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()) :

1. $url : URL of the sioc:Post (HTML)
2. $subject : Subject of the sioc:Post (i.e. its title)
3. $content : Content of the sioc:Post (plain-text)
4. $encoded : HTML content of the sioc:Post
5. $creator : Creator of the sioc:Post  Must be an instance of SIOCUser, not a string
6. $created : Creation date of the sioc:Post
7. $updated : Update date of the sioc:Post
8. $topic : Array of topics of the sioc:Post (see below)
9. $links : Array of links extracted from the sioc:Post (see below)
10. 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) :

1. $id : ID of the sioc:Post which is a comment of the current Post (the API does not yet use sioc Types module)
2. $url : URL of the Comment (HTML)
3. NB: You can add as many comments as needed
4. 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) :

1. $id : ID of the sioc:Post which this post comments
2. $url : URL of the original post (HTML)
3. 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);
            }
        }
    }