Home » API reference

blogapi.module

<?php
// $Id: blogapi.module,v 1.39.2.11 2005/11/30 10:05:16 dries Exp $

/**
 * @file
 * Enable users to post using applications that support XML-RPC blog APIs.
 */

/**
 * Implementation of hook_help().
 */
function blogapi_help($section) {
  switch ($section) {
    case 'admin/help#blogapi':
      return t('<p>This module adds support for several XML-RPC based blogging APIs. Specifically, it currently implements the %bloggerAPI, %metaweblogAPI, and most of the %moveabletype extensions.  This allows users to contribute to Drupal using external GUI applications, which can often offer richer functionality that online forms based editing.</p><p>This module also allows site administrators to configure which node types can be posted via the external applications. So, for instance, users can post forum topics as well as blog posts. Where supported, the external applications will display each node type as a separate "blog".</p>', array('%bloggerAPI' => '<a href="http://www.blogger.com/developers/api/1_docs/">Blogger API</a>', '%metaweblogAPI' => '<a href="http://www.xmlrpc.com/metaWeblogApi">MetaWeblog API</a>', '%moveabletype' => '<a href="http://www.movabletype.org/docs/mtmanual_programmatic.html">Movable Type API</a>. '));
    case 'admin/modules#description':
      return t('Allows users to post content using applications that support XML-RPC blog APIs.');
  }
}

/**
 * Implementation of hook_xmlrpc().
 */
function blogapi_xmlrpc() {
  return array(
    array(
      'blogger.getUsersBlogs',
      'blogapi_blogger_get_users_blogs',
      array('array', 'string', 'string', 'string'),
      t('Returns a list of weblogs to which an author has posting privileges.')),
    array(
      'blogger.getUserInfo',
      'blogapi_blogger_get_user_info',
      array('struct', 'string', 'string', 'string'),
      t('Returns information about an author in the system.')),
    array(
      'blogger.newPost',
      'blogapi_blogger_new_post',
      array('string', 'string', 'string', 'string', 'string', 'string', 'boolean'),
      t('Creates a new post, and optionally publishes it.')),
    array(
      'blogger.editPost',
      'blogapi_blogger_edit_post',
      array('boolean', 'string', 'string', 'string', 'string', 'string', 'boolean'),
      t('Updates the information about an existing post.')),
    array(
      'blogger.getPost',
      'blogapi_blogger_get_post',
      array('struct', 'string', 'string', 'string', 'string'),
      t('Returns information about a specific post.')),
    array(
      'blogger.deletePost',
      'blogapi_blogger_delete_post',
      array('boolean', 'string', 'string', 'string', 'string', 'boolean'),
      t('Deletes a post.')),
    array(
      'blogger.getRecentPosts',
      'blogapi_blogger_get_recent_posts',
      array('array', 'string', 'string', 'string', 'string', 'int'),
      t('Returns a list of the most recent posts in the system.')),
    array(
      'metaWeblog.newPost',
      'blogapi_metaweblog_new_post',
      array('string', 'string', 'string', 'string', 'struct', 'boolean'),
      t('Creates a new post, and optionally publishes it.')),
    array(
      'metaWeblog.editPost',
      'blogapi_metaweblog_edit_post',
      array('boolean', 'string', 'string', 'string', 'struct', 'boolean'),
      t('Updates information about an existing post.')),
    array(
      'metaWeblog.getPost',
      'blogapi_metaweblog_get_post',
      array('struct', 'string', 'string', 'string'),
      t('Returns information about a specific post.')),
    array(
      'metaWeblog.newMediaObject',
      'blogapi_metaweblog_new_media_object',
      array('string', 'string', 'string', 'string', 'struct'),
      t('Uploads a file to your webserver.')),
    array(
      'metaWeblog.getCategories',
      'blogapi_metaweblog_get_category_list',
      array('struct', 'string', 'string', 'string'),
      t('Returns a list of all categories to which the post is assigned.')),
    array(
      'metaWeblog.getRecentPosts',
      'blogapi_metaweblog_get_recent_posts',
      array('array', 'string', 'string', 'string', 'int'),
      t('Returns a list of the most recent posts in the system.')),
    array(
      'mt.getRecentPostTitles',
      'blogapi_mt_get_recent_post_titles',
      array('array', 'string', 'string', 'string', 'int'),
      t('Returns a bandwidth-friendly list of the most recent posts in the system.')),
    array(
      'mt.getCategoryList',
      'blogapi_mt_get_category_list',
      array('array', 'string', 'string', 'string'),
      t('Returns a list of all categories defined in the weblog.')),
    array(
      'mt.getPostCategories',
      'blogapi_mt_get_post_categories',
      array('array', 'string', 'string', 'string'),
      t('Returns a list of all categories to which the post is assigned.')),
    array(
      'mt.setPostCategories',
      'blogapi_mt_set_post_categories',
      array('boolean', 'string', 'string', 'string', 'array'),
      t('Sets the categories for a post.')),
    array(
      'mt.supportedMethods',
      'xmlrpc_server_list_methods',
      array('array'),
      t('Retrieve information about the XML-RPC methods supported by the server.')),
    array(
      'mt.supportedTextFilters',
      'blogapi_mt_supported_text_filters',
      array('array'),
      t('Retrieve information about the text formatting plugins supported by the server.')),
    array(
      'mt.getTrackbackPings',
      'blogapi_mt_get_trackback_pings',
      array('array', 'string'),
      t('Retrieve the list of TrackBack pings posted to a particular entry. This could be used to programmatically retrieve the list of pings for a particular entry, then iterate through each of those pings doing the same, until one has built up a graph of the web of entries referencing one another on a particular topic.')),
    array(
      'mt.publishPost',
      'blogap_mti_publish_post',
      array('boolean', 'string', 'string', 'string'),
      t('Publish (rebuild) all of the static files related to an entry from your weblog. Equivalent to saving an entry in the system (but without the ping).')));
}

/**
 * Blogging API callback. Finds the URL of a user's blog.
 */

function blogapi_blogger_get_users_blogs($appid, $username, $password) {

  $user = blogapi_validate_user($username, $password);
  if ($user->uid) {
    $types = _blogapi_get_node_types();
    $structs = array();
    foreach ($types as $type) {
      $structs[] = array('url' => url('blog/' . $user->uid, NULL, NULL, true), 'blogid' => $type, 'blogName' => $user->name . ": " . $type);
    }
    return $structs;
  }
  else {
    return blogapi_error($user);
  }
}

/**
 * Blogging API callback. Returns profile information about a user.
 */
function blogapi_blogger_get_user_info($appkey, $username, $password) {
  $user = blogapi_validate_user($username, $password);

  if ($user->uid) {
    $name = explode(' ', $user->realname ? $user->realname : $user->name, 2);
    return array(
      'userid' => $user->uid,
      'lastname' => $name[1],
      'firstname' => $name[0],
      'nickname' => $user->name,
      'email' => $user->mail,
      'url' => url('blog/' . $user->uid, NULL, NULL, true));
  }
  else {
    return blogapi_error($user);
  }
}

/**
 * Blogging API callback. Inserts a new blog post as a node.
 */
function blogapi_blogger_new_post($appkey, $blogid, $username, $password, $content, $publish) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $edit = array();
  $edit['type'] = _blogapi_blogid($blogid);
  // get the node type defaults
  $node_type_default = variable_get('node_options_'. $edit['type'], array('status', 'promote'));
  $edit['uid'] = $user->uid;
  $edit['name'] = $user->name;
  $edit['promote'] = in_array('promote', $node_type_default);
  $edit['comment'] = variable_get('comment_'. $edit['type'], 2);
  $edit['moderate'] = in_array('moderate', $node_type_default);
  $edit['revision'] = in_array('revision', $node_type_default);
  $edit['format'] = FILTER_FORMAT_DEFAULT;
  $edit['status'] = $publish;

  // check for bloggerAPI vs. metaWeblogAPI
  if (is_array($content)) {
    $edit['title'] = $content['title'];
    $edit['body'] = $content['description'];
    _blogapi_mt_extra($edit, $content);
  }
  else {
    $edit['title'] = blogapi_blogger_title($content);
    $edit['body'] = $content;
  }

  $node = node_validate($edit);

  if ($errors = form_get_errors()) {
    return blogapi_error(implode("\n", $errors));
  }

  if (!node_access('create', $node)) {
    return blogapi_error(message_access());
  }

  $nid = node_save($node);
  if ($nid) {
    watchdog('content', t('%type: added %title using blog API.', array('%type' => '<em>'. t($node->type) .'</em>', '%title' => theme('placeholder', $node->title))), WATCHDOG_NOTICE, l(t('view'), "node/$nid"));
    // blogger.newPost returns a string
    return "$nid";
  }

  return blogapi_error(t('Error storing post.'));
}

/**
 * Blogging API callback. Modifies the specified blog node.
 */
function blogapi_blogger_edit_post($appkey, $postid, $username, $password, $content, $publish) {

  $user = blogapi_validate_user($username, $password);

  if (!$user->uid) {
    return blogapi_error($user);
  }

  $node = node_load(array('nid' => $postid));
  if (!$node) {
    return blogapi_error(message_na());
  }
  // Let the teaser be re-generated.
  unset($node->teaser);

  if (!node_access('update', $node)) {
    return blogapi_error(message_access());
  }

  $node->status = $publish;

  // check for bloggerAPI vs. metaWeblogAPI
  if (is_array($content)) {
    $node->title = $content['title'];
    $node->body = $content['description'];
    _blogapi_mt_extra($node, $content);
  }
  else {
    $node->title = blogapi_blogger_title($content);
    $node->body = $content;
  }

  $node = node_validate($node);

  if ($errors = form_get_errors()) {
    return blogapi_error(implode("\n", $errors));
  }

  $terms = module_invoke('taxonomy', 'node_get_terms', $node->nid, 'tid');
  foreach ($terms as $term) {
    $node->taxonomy[] = $term->tid;
  }
  $nid = node_save($node);
  if ($nid) {
    watchdog('content', t('%type: updated %title using blog API.', array('%type' => '<em>'. t($node->type) .'</em>', '%title' => theme('placeholder', $node->title))), WATCHDOG_NOTICE, l(t('view'), "node/$nid"));
    return true;
  }

  return blogapi_error(t('Error storing post.'));
}

/**
 * Blogging API callback. Returns a specified blog node.
 */
function blogapi_blogger_get_post($appkey, $postid, $username, $password) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $node = node_load(array('nid' => $postid));

  return _blogapi_get_post($node, true);
}

/**
 * Blogging API callback. Removes the specified blog node.
 */
function blogapi_blogger_delete_post($appkey, $postid, $username, $password, $publish) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  node_delete(array('nid' => $postid, 'confirm' => 1));
  return true;
}

/**
 * Blogging API callback. Returns the latest few postings in a user's blog. $bodies TRUE
 * <a href="http://movabletype.org/docs/mtmanual_programmatic.html#item_mt%2EgetRecentPostTitles">
 * returns a bandwidth-friendly list</a>.
 */
function blogapi_blogger_get_recent_posts($appkey, $blogid, $username, $password, $number_of_posts, $bodies = TRUE) {
  // Remove unused appkey (from bloggerAPI).
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $type = _blogapi_blogid($blogid);
  $result = db_query_range('SELECT n.nid, n.title,'. ($bodies ? ' n.body,' : '') ." n.created, u.name FROM {node} n, {users} u WHERE n.uid=u.uid AND n.type = '%s' AND n.uid = %d ORDER BY n.created DESC", $type, $user->uid, 0, $number_of_posts);
  $blogs = array ();
  while ($blog = db_fetch_object($result)) {
    $blogs[] = _blogapi_get_post($blog, $bodies);
  }
  return $blogs;
}

function blogapi_metaweblog_new_post($blogid, $username, $password, $content, $publish) {
  return blogapi_blogger_new_post('0123456789ABCDEF', $blogid, $username, $password, $content, $publish);
}

function blogapi_metaweblog_edit_post($postid, $username, $password, $content, $publish) {
  return blogapi_blogger_edit_post('0123456789ABCDEF', $postid, $username, $password, $content, $publish);
}

function blogapi_metaweblog_get_post($postid, $username, $password) {
  return blogapi_blogger_get_post('01234567890ABCDEF', $postid, $username, $password);
}

/**
 * Blogging API callback. Inserts a file into Drupal.
 */
function blogapi_metaweblog_new_media_object($blogid, $username, $password, $file) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $name = basename($file['name']);
  $data = $file['bits'];

  if (!$data) {
    return blogapi_error(t('No file sent.'));
  }

  if (!$file = file_save_data($data, $name)) {
    return blogapi_error(t('Error storing file.'));
  }

  // Return the successful result.
  return array('url' => file_create_url($file), 'struct');
}
/**
 * Blogging API callback. Returns a list of the taxonomy terms that can be
 * associated with a blog node.
 */
function blogapi_metaweblog_get_category_list($blogid, $username, $password) {
  $type = _blogapi_blogid($blogid);
  $vocabularies = module_invoke('taxonomy', 'get_vocabularies', $type, 'vid');
  $categories = array();
  if ($vocabularies) {
    foreach ($vocabularies as $vocabulary) {
      $terms = module_invoke('taxonomy', 'get_tree', $vocabulary->vid, 0, -1);
      foreach ($terms as $term) {
        $term_name = $term->name;
        foreach (module_invoke('taxonomy', 'get_parents', $term->tid, 'tid') as $parent) {
          $term_name = $parent->name . '/' . $term_name;
        }
        $categories[] = array('categoryName' => $term_name, 'categoryId' => $term->tid);
      }
    }
  }
  return $categories;
}

function blogapi_metaweblog_get_recent_posts($blogid, $username, $password, $number_of_posts) {
  return blogapi_blogger_get_recent_posts('0123456789ABCDEF', $blogid, $username, $password, $number_of_posts, TRUE);
}

// see above
function blogapi_mt_get_recent_post_titles($blogid, $username, $password, $number_of_posts) {
  return blogapi_blogger_get_recent_posts('0123456789ABCDEF', $blogid, $username, $password, $number_of_posts, FALSE);
}

/* **** */
function blogapi_mt_get_category_list($blogid, $username, $password) {
  return blogapi_metaweblog_get_category_list($blogid, $username, $password);
}

/**
 * Blogging API callback. Returns a list of the taxonomy terms that are
 * assigned to a particular node.
 */
function blogapi_mt_get_post_categories($postid, $username, $password) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $terms = module_invoke('taxonomy', 'node_get_terms', $postid, 'tid');
  $categories = array();
  foreach ($terms as $term) {
    $term_name = $term->name;
    foreach (module_invoke('taxonomy', 'get_parents', $term->tid, 'tid') as $parent) {
      $term_name = $parent->name . '/' . $term_name;
    }
    $categories[] = array('categoryName' => $term_name, 'categoryId' => $term->tid, 'isPrimary' => true);
  }
  return $categories;
}

/**
 * Blogging API callback. Assigns taxonomy terms to a particular node.
 */
function blogapi_mt_set_post_categories($postid, $username, $password, $categories) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }

  $nid = $postid;
  $terms = array();
  foreach ($categories as $category) {
    $terms[] = $category['categoryId'];
  }
  module_invoke('taxonomy', 'node_save', $nid, $terms);
  return true;
}

/**
 * Blogging API callback. Sends a list of available input formats.
 */
function blogapi_mt_supported_text_filters() {
  // NOTE: we're only using anonymous' formats because the MT spec
  // does not allow for per-user formats.
  $formats = filter_formats();

  $filters = array();
  foreach ($formats as $format) {
    $filter['key'] = $format->format;
    $filter['label'] = $format->name;
    $filters[] = $filter;
  }

  return $filters;
}

/**
 * Blogging API callback. Can not be implemented without support from
 * trackback module.
 */
function blogapi_mt_get_trackback_pings() {
  return blogapi_error(t('Not implemented.'));
}

/**
 * Blogging API callback. Publishes the given node
 */
function blogap_mti_publish_post($postid, $username, $password) {
  $user = blogapi_validate_user($username, $password);
  if (!$user->uid) {
    return blogapi_error($user);
  }
  $node = node_load(array('nid' => $postid));
  if (!$node) {
    return blogapi_error(t('Invalid post.'));
  }

  $node->status = 1;
  if (!node_access('update', $node)) {
    return blogapi_error(message_access());
  }

  $terms = module_invoke('taxonomy', 'node_get_terms', $node->nid, 'tid');
  foreach ($terms as $term) {
    $node->taxonomy[] = $term->tid;
  }
  node_save($node);

  return true;
}

/**
 * Prepare an error message for returning to the XMLRPC caller.
 */
function blogapi_error($message) {
  static $xmlrpcusererr;
  if (!is_array($message)) {
    $message = array($message);
  }

  $message = implode(' ', $message);

  return xmlrpc_error($xmlrpcusererr + 1, strip_tags($message));
}

/**
 * Ensure that the given user has permission to edit a blog.
 */
function blogapi_validate_user($username, $password) {
  global $user;

  $user = user_authenticate($username, $password);

  if ($user->uid) {
    if (user_access('edit own blog', $user)) {
      return $user;
    }
    else {
      return message_access();
    }
  }
  else {
    return t('Wrong username or password.');
  }
}

/**
 * For the blogger API, extract the node title from the contents field.
 */
function blogapi_blogger_title(&$contents) {
  if (eregi('<title>([^<]*)</title>', $contents, $title)) {
    $title = strip_tags($title[0]);
    $contents = ereg_replace('<title>[^<]*</title>', '', $contents);
  }
  else {
    list($title, $contents) = explode("\n", $contents, 2);
  }
  return $title;
}

function blogapi_settings() {
  $output = form_select(t('XML-RPC Engine'), 'blogapi_engine', variable_get('blogapi_engine', 0), array(0 => 'Blogger', 1 => 'MetaWeblog', 2 => 'Movabletype'), t('RSD or Really-Simple-Discovery is a mechanism which allows external blogger tools to discover the APIs they can use to interact with Drupal. Here you can set the preferred method for blogger tools to interact with your site. The common XML-RPC engines are Blogger, MetaWeblog and Movabletype. If you are not sure which is the correct setting, choose Blogger.'));
  foreach (node_list() as $type) {
    $node_types[$type] = node_invoke($type, 'node_name');
    if (in_array($type, array('blog'))) {
      $defaults[] = $type;
    }
  }
  $output .= form_checkboxes(t('Blog types'), "blogapi_node_types", variable_get('blogapi_node_types', $defaults), $node_types, t('Select the content types for which you wish to enable posting via blogapi. Each type will appear as a different "blog" in the client application (if supported).'), 0, 1);
  return $output;
}

function blogapi_menu($may_cache) {
  $items = array();

  if ($_GET['q'] == variable_get('site_frontpage', 'node')) {
    drupal_add_link(array('rel' => 'EditURI',
                          'type' => 'application/rsd+xml',
                          'title' => t('RSD'),
                          'href' => url('blogapi/rsd', NULL, NULL, TRUE)));
  }

  if ($may_cache) {
    $items[] = array('path' => 'blogapi', 'title' => t('RSD'), 'callback' => 'blogapi_blogapi', 'access' => user_access('access content'), 'type' => MENU_CALLBACK);
  }

  return $items;
}

function blogapi_blogapi() {
  switch (arg(1)) {
    case 'rsd':
      blogapi_rsd();
      break;
    default:
      drupal_not_found();
      break;
  }
}

function blogapi_rsd() {
  global $base_url;

  $xmlrpc = $base_url .'/'. 'xmlrpc.php';
  $base = url('', NULL, NULL, TRUE);
  $blogid = 1; # until we figure out how to handle multiple bloggers

  $metaweblog = 'false'; $blogger = 'false'; $mt = 'false';
  if (variable_get('blogapi_engine', 0) == 0) {
    $blogger = 'true';
  } else if (variable_get('blogapi_engine', 0) == 1) {
    $metaweblog = 'true';
  } else if (variable_get('blogapi_engine', 0) == 2) {
    $mt = 'true';
  }

  drupal_set_header('Content-Type: application/rsd+xml; charset=utf-8');
  print <<<__RSD__
<?xml version="1.0"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
  <service>
    <engineName>Drupal</engineName>
    <engineLink>http://www.drupal.org/</engineLink>
    <homePageLink>$base</homePageLink>
    <apis>
      <api name="MetaWeblog" preferred="$metaweblog" apiLink="$xmlrpc" blogID="$blogid" />
      <api name="Blogger" preferred="$blogger" apiLink="$xmlrpc" blogID="$blogid" />
      <api name="MovableType" preferred="$mt" apiLink="$xmlrpc" blogID="$blogid" />
    </apis>
  </service>
</rsd>
__RSD__;
}

/**
 * Handles extra information sent by clients according to MovableType's spec.
 */
function _blogapi_mt_extra(&$node, $struct) {
  if (is_array($node)) {
    $was_array = true;
    $node = array2object($node);
  }

  // mt_allow_comments
  if (array_key_exists('mt_allow_comments', $struct)) {
    switch ($struct['mt_allow_comments']) {
      case 0:
        $node->comment = 0;
        break;
      case 1:
        $node->comment = 2;
        break;
      case 2:
        $node->comment = 1;
        break;
    }
  }

  // merge the 3 body sections (description, mt_excerpt, mt_text_more) into
  // one body
  if ($struct['mt_excerpt']) {
    $node->body = $struct['mt_excerpt'] .'<!--break-->'.$node->body;
  }
  if ($struct['mt_text_more']) {
    $node->body = $node->body . '<!--extended-->' . $struct['mt_text_more'];
  }

  // mt_tb_ping_urls
  if (function_exists('trackback_send')) {
    if (is_array($struct['mt_tb_ping_urls'])) {
      foreach ($struct['mt_tb_ping_urls'] as $tb_ping_url) {
        $node->tb_url = $tb_ping_url->getVal();
        trackback_send($node);
        unset($node->tb_url); // make sure we don't ping twice
      }
    }
    else {
      $node->tb_url = $struct['mt_tb_ping_urls'];
    }
  }

  // mt_convert_breaks
  if ($struct['mt_convert_breaks']) {
    $node->format = $struct['mt_convert_breaks'];
  }

  // dateCreated
  if ($struct['dateCreated']) {
    $node->created = mktime($struct['dateCreated']->hour, $struct['dateCreated']->minute, $struct['dateCreated']->second, $struct['dateCreated']->month, $struct['dateCreated']->day, $struct['dateCreated']->year);
  }

  if ($was_array) {
    $node = object2array($node);
  }
}

function _blogapi_get_post($node, $bodies = true) {
  $xmlrpcval = array (
    'userid' => $node->name,
    'dateCreated' => xmlrpc_date($node->created),
    'title' => $node->title,
    'postid' => $node->nid,
    'link' => url('node/'.$node->nid, NULL, NULL, true),
    'permaLink' => url('node/'.$node->nid, NULL, NULL, true),
  );
  if ($bodies) {
    if ($node->comment = 1) {
      $comment = 2;
    }
    if ($node->comment = 2) {
      $comment = 1;
    }

    $xmlrpcval['content'] = "<title>$node->title</title>$node->body";
    $xmlrpcval['description'] = $node->body;
    // Add MT specific fields
    $xmlrpcval['mt_allow_comments'] = $comment;
    $xmlrpcval['mt_convert_breaks'] = $node->format;
  }

  return $xmlrpcval;
}

function _blogapi_blogid($id) {
  if (is_numeric($id)) {
    return 'blog';
  }
  else {
    return $id;
  }
}

function _blogapi_get_node_types() {
  $available_types = variable_get('blogapi_node_types', array('blog'));
  $types = array();
  foreach (node_list() as $type) {
    if (node_access('create', $type) && in_array($type, $available_types)) {
      $types[] = $type;
    }
  }

  return $types;
}
?>
 
 

All source code and documentation on this site is released under the terms of the GNU General Public License, version 2 and later. Drupal is a registered trademark of Dries Buytaert.