/extlib/facebook/facebookapi_php5_restlib.php

Large files files are truncated, but you can click here to view the full file

<?php
// Copyright 2004-2009 Facebook. All Rights Reserved.
//
// +---------------------------------------------------------------------------+
// | Facebook Platform PHP5 client                                             |
// +---------------------------------------------------------------------------+
// | Copyright (c) 2007-2009 Facebook, Inc.                                    |
// | All rights reserved.                                                      |
// |                                                                           |
// | Redistribution and use in source and binary forms, with or without        |
// | modification, are permitted provided that the following conditions        |
// | are met:                                                                  |
// |                                                                           |
// | 1. Redistributions of source code must retain the above copyright         |
// |    notice, this list of conditions and the following disclaimer.          |
// | 2. Redistributions in binary form must reproduce the above copyright      |
// |    notice, this list of conditions and the following disclaimer in the    |
// |    documentation and/or other materials provided with the distribution.   |
// |                                                                           |
// | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR      |
// | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
// | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.   |
// | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,          |
// | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT  |
// | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
// | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     |
// | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       |
// | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF  |
// | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.         |
// +---------------------------------------------------------------------------+
// | For help with this library, contact developers-help@facebook.com          |
// +---------------------------------------------------------------------------+
//

include_once 'jsonwrapper/jsonwrapper.php';

class FacebookRestClient {
  public $secret;
  public $session_key;
  public $api_key;
  // to save making the friends.get api call, this will get prepopulated on
  // canvas pages
  public $friends_list;
  public $user;
  // to save making the pages.isAppAdded api call, this will get prepopulated
  // on canvas pages
  public $added;
  public $is_user;
  // we don't pass friends list to iframes, but we want to make
  // friends_get really simple in the canvas_user (non-logged in) case.
  // So we use the canvas_user as default arg to friends_get
  public $canvas_user;
  public $batch_mode;
  private $batch_queue;
  private $pending_batch;
  private $call_as_apikey;
  private $use_curl_if_available;

  const BATCH_MODE_DEFAULT = 0;
  const BATCH_MODE_SERVER_PARALLEL = 0;
  const BATCH_MODE_SERIAL_ONLY = 2;

  /**
   * Create the client.
   * @param string $session_key if you haven't gotten a session key yet, leave
   *                            this as null and then set it later by just
   *                            directly accessing the $session_key member
   *                            variable.
   */
  public function __construct($api_key, $secret, $session_key=null) {
    $this->secret       = $secret;
    $this->session_key  = $session_key;
    $this->api_key      = $api_key;
    $this->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
    $this->last_call_id = 0;
    $this->call_as_apikey = '';
    $this->use_curl_if_available = true;
    $this->server_addr  = Facebook::get_facebook_url('api') . '/restserver.php';

    if (!empty($GLOBALS['facebook_config']['debug'])) {
      $this->cur_id = 0;
      ?>
<script type="text/javascript">
var types = ['params', 'xml', 'php', 'sxml'];
function getStyle(elem, style) {
  if (elem.getStyle) {
    return elem.getStyle(style);
  } else {
    return elem.style[style];
  }
}
function setStyle(elem, style, value) {
  if (elem.setStyle) {
    elem.setStyle(style, value);
  } else {
    elem.style[style] = value;
  }
}
function toggleDisplay(id, type) {
  for (var i = 0; i < types.length; i++) {
    var t = types[i];
    var pre = document.getElementById(t + id);
    if (pre) {
      if (t != type || getStyle(pre, 'display') == 'block') {
        setStyle(pre, 'display', 'none');
      } else {
        setStyle(pre, 'display', 'block');
      }
    }
  }
  return false;
}
</script>
<?php
    }
  }

  /**
   * Set the default user id for methods that allow the caller
   * to pass an uid parameter to identify the target user
   * instead of a session key. This currently applies to
   * the user preferences methods.
   *
   * @param $uid int the user id
   */
  public function set_user($uid) {
    $this->user = $uid;
  }

  /**
   * Normally, if the cURL library/PHP extension is available, it is used for
   * HTTP transactions.  This allows that behavior to be overridden, falling
   * back to a vanilla-PHP implementation even if cURL is installed.
   *
   * @param $use_curl_if_available bool whether or not to use cURL if available
   */
  public function set_use_curl_if_available($use_curl_if_available) {
    $this->use_curl_if_available = $use_curl_if_available;
  }

  /**
   * Start a batch operation.
   */
  public function begin_batch() {
    if ($this->pending_batch()) {
      $code = FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED;
      $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
      throw new FacebookRestClientException($description, $code);
    }

    $this->batch_queue = array();
    $this->pending_batch = true;
  }

  /*
   * End current batch operation
   */
  public function end_batch() {
    if (!$this->pending_batch()) {
      $code = FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED;
      $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
      throw new FacebookRestClientException($description, $code);
    }

    $this->pending_batch = false;

    $this->execute_server_side_batch();
    $this->batch_queue = null;
  }

  /**
   * are we currently queueing up calls for a batch?
   */
  public function pending_batch() {
    return $this->pending_batch;
  }

  private function execute_server_side_batch() {
    $item_count = count($this->batch_queue);
    $method_feed = array();
    foreach($this->batch_queue as $batch_item) {
      $method = $batch_item['m'];
      $params = $batch_item['p'];
      $this->finalize_params($method, $params);
      $method_feed[] = $this->create_post_string($method, $params);
    }

    $method_feed_json = json_encode($method_feed);

    $serial_only =
      ($this->batch_mode == FacebookRestClient::BATCH_MODE_SERIAL_ONLY);
    $params = array('method_feed' => $method_feed_json,
                    'serial_only' => $serial_only);
    if ($this->call_as_apikey) {
      $params['call_as_apikey'] = $this->call_as_apikey;
    }

    $xml = $this->post_request('batch.run', $params);

    $result = $this->convert_xml_to_result($xml, 'batch.run', $params);


    if (is_array($result) && isset($result['error_code'])) {
      throw new FacebookRestClientException($result['error_msg'],
                                            $result['error_code']);
    }

    for($i = 0; $i < $item_count; $i++) {
      $batch_item = $this->batch_queue[$i];
      $batch_item_result_xml = $result[$i];
      $batch_item_result = $this->convert_xml_to_result($batch_item_result_xml,
                                                        $batch_item['m'],
                                                        $batch_item['p']);

      if (is_array($batch_item_result) &&
          isset($batch_item_result['error_code'])) {
        throw new FacebookRestClientException($batch_item_result['error_msg'],
                                              $batch_item_result['error_code']);
      }
      $batch_item['r'] = $batch_item_result;
    }
  }

  public function begin_permissions_mode($permissions_apikey) {
    $this->call_as_apikey = $permissions_apikey;
  }

  public function end_permissions_mode() {
    $this->call_as_apikey = '';
  }


  /*
   * If a page is loaded via HTTPS, then all images and static
   * resources need to be printed with HTTPS urls to avoid
   * mixed content warnings. If your page loads with an HTTPS
   * url, then call set_use_ssl_resources to retrieve the correct
   * urls.
   */
  public function set_use_ssl_resources($is_ssl = true) {
    $this->use_ssl_resources = $is_ssl;
  }

  /**
   * Returns public information for an application (as shown in the application
   * directory) by either application ID, API key, or canvas page name.
   *
   * @param int $application_id              (Optional) app id
   * @param string $application_api_key      (Optional) api key
   * @param string $application_canvas_name  (Optional) canvas name
   *
   * Exactly one argument must be specified, otherwise it is an error.
   *
   * @return array  An array of public information about the application.
   */
  public function application_getPublicInfo($application_id=null,
                                            $application_api_key=null,
                                            $application_canvas_name=null) {
    return $this->call_method('facebook.application.getPublicInfo',
        array('application_id' => $application_id,
              'application_api_key' => $application_api_key,
              'application_canvas_name' => $application_canvas_name));
  }

  /**
   * Creates an authentication token to be used as part of the desktop login
   * flow.  For more information, please see
   * http://wiki.developers.facebook.com/index.php/Auth.createToken.
   *
   * @return string  An authentication token.
   */
  public function auth_createToken() {
    return $this->call_method('facebook.auth.createToken');
  }

  /**
   * Returns the session information available after current user logs in.
   *
   * @param string $auth_token             the token returned by
   *                                       auth_createToken or passed back to
   *                                       your callback_url.
   * @param bool $generate_session_secret  whether the session returned should
   *                                       include a session secret
   *
   * @return array  An assoc array containing session_key, uid
   */
  public function auth_getSession($auth_token, $generate_session_secret=false) {
    if (!$this->pending_batch()) {
      $result = $this->call_method('facebook.auth.getSession',
          array('auth_token' => $auth_token,
                'generate_session_secret' => $generate_session_secret));
      $this->session_key = $result['session_key'];

    if (!empty($result['secret']) && !$generate_session_secret) {
      // desktop apps have a special secret
      $this->secret = $result['secret'];
    }
      return $result;
    }
  }

  /**
   * Generates a session-specific secret. This is for integration with
   * client-side API calls, such as the JS library.
   *
   * @return array  A session secret for the current promoted session
   *
   * @error API_EC_PARAM_SESSION_KEY
   *        API_EC_PARAM_UNKNOWN
   */
  public function auth_promoteSession() {
      return $this->call_method('facebook.auth.promoteSession');
  }

  /**
   * Expires the session that is currently being used.  If this call is
   * successful, no further calls to the API (which require a session) can be
   * made until a valid session is created.
   *
   * @return bool  true if session expiration was successful, false otherwise
   */
  public function auth_expireSession() {
      return $this->call_method('facebook.auth.expireSession');
  }

  /**
   *  Revokes the given extended permission that the user granted at some
   *  prior time (for instance, offline_access or email).  If no user is
   *  provided, it will be revoked for the user of the current session.
   *
   *  @param  string  $perm  The permission to revoke
   *  @param  int     $uid   The user for whom to revoke the permission.
   */
  public function auth_revokeExtendedPermission($perm, $uid=null) {
    return $this->call_method('facebook.auth.revokeExtendedPermission',
        array('perm' => $perm, 'uid' => $uid));
  }

  /**
   * Revokes the user's agreement to the Facebook Terms of Service for your
   * application.  If you call this method for one of your users, you will no
   * longer be able to make API requests on their behalf until they again
   * authorize your application.  Use with care.  Note that if this method is
   * called without a user parameter, then it will revoke access for the
   * current session's user.
   *
   * @param int $uid  (Optional) User to revoke
   *
   * @return bool  true if revocation succeeds, false otherwise
   */
  public function auth_revokeAuthorization($uid=null) {
      return $this->call_method('facebook.auth.revokeAuthorization',
          array('uid' => $uid));
  }

  /**
   * Get public key that is needed to verify digital signature
   * an app may pass to other apps. The public key is only used by
   * other apps for verification purposes.
   * @param  string  API key of an app
   * @return string  The public key for the app.
   */
  public function auth_getAppPublicKey($target_app_key) {
    return $this->call_method('facebook.auth.getAppPublicKey',
          array('target_app_key' => $target_app_key));
  }

  /**
   * Get a structure that can be passed to another app
   * as proof of session. The other app can verify it using public
   * key of this app.
   *
   * @return signed public session data structure.
   */
  public function auth_getSignedPublicSessionData() {
    return $this->call_method('facebook.auth.getSignedPublicSessionData',
                              array());
  }

  /**
   * Returns the number of unconnected friends that exist in this application.
   * This number is determined based on the accounts registered through
   * connect.registerUsers() (see below).
   */
  public function connect_getUnconnectedFriendsCount() {
    return $this->call_method('facebook.connect.getUnconnectedFriendsCount',
        array());
  }

 /**
  * This method is used to create an association between an external user
  * account and a Facebook user account, as per Facebook Connect.
  *
  * This method takes an array of account data, including a required email_hash
  * and optional account data. For each connected account, if the user exists,
  * the information is added to the set of the user's connected accounts.
  * If the user has already authorized the site, the connected account is added
  * in the confirmed state. If the user has not yet authorized the site, the
  * connected account is added in the pending state.
  *
  * This is designed to help Facebook Connect recognize when two Facebook
  * friends are both members of a external site, but perhaps are not aware of
  * it.  The Connect dialog (see fb:connect-form) is used when friends can be
  * identified through these email hashes. See the following url for details:
  *
  *   http://wiki.developers.facebook.com/index.php/Connect.registerUsers
  *
  * @param mixed $accounts A (JSON-encoded) array of arrays, where each array
  *                        has three properties:
  *                        'email_hash'  (req) - public email hash of account
  *                        'account_id'  (opt) - remote account id;
  *                        'account_url' (opt) - url to remote account;
  *
  * @return array  The list of email hashes for the successfully registered
  *                accounts.
  */
  public function connect_registerUsers($accounts) {
    return $this->call_method('facebook.connect.registerUsers',
        array('accounts' => $accounts));
  }

 /**
  * Unregisters a set of accounts registered using connect.registerUsers.
  *
  * @param array $email_hashes  The (JSON-encoded) list of email hashes to be
  *                             unregistered.
  *
  * @return array  The list of email hashes which have been successfully
  *                unregistered.
  */
  public function connect_unregisterUsers($email_hashes) {
    return $this->call_method('facebook.connect.unregisterUsers',
        array('email_hashes' => $email_hashes));
  }

  /**
   * Returns events according to the filters specified.
   *
   * @param int $uid            (Optional) User associated with events. A null
   *                            parameter will default to the session user.
   * @param array/string $eids  (Optional) Filter by these event
   *                            ids. A null parameter will get all events for
   *                            the user. (A csv list will work but is deprecated)
   * @param int $start_time     (Optional) Filter with this unix time as lower
   *                            bound.  A null or zero parameter indicates no
   *                            lower bound.
   * @param int $end_time       (Optional) Filter with this UTC as upper bound.
   *                            A null or zero parameter indicates no upper
   *                            bound.
   * @param string $rsvp_status (Optional) Only show events where the given uid
   *                            has this rsvp status.  This only works if you
   *                            have specified a value for $uid.  Values are as
   *                            in events.getMembers.  Null indicates to ignore
   *                            rsvp status when filtering.
   *
   * @return array  The events matching the query.
   */
  public function &events_get($uid=null,
                              $eids=null,
                              $start_time=null,
                              $end_time=null,
                              $rsvp_status=null) {
    return $this->call_method('facebook.events.get',
        array('uid' => $uid,
              'eids' => $eids,
              'start_time' => $start_time,
              'end_time' => $end_time,
              'rsvp_status' => $rsvp_status));
  }

  /**
   * Returns membership list data associated with an event.
   *
   * @param int $eid  event id
   *
   * @return array  An assoc array of four membership lists, with keys
   *                'attending', 'unsure', 'declined', and 'not_replied'
   */
  public function &events_getMembers($eid) {
    return $this->call_method('facebook.events.getMembers',
      array('eid' => $eid));
  }

  /**
   * RSVPs the current user to this event.
   *
   * @param int $eid             event id
   * @param string $rsvp_status  'attending', 'unsure', or 'declined'
   *
   * @return bool  true if successful
   */
  public function &events_rsvp($eid, $rsvp_status) {
    return $this->call_method('facebook.events.rsvp',
        array(
        'eid' => $eid,
        'rsvp_status' => $rsvp_status));
  }

  /**
   * Cancels an event. Only works for events where application is the admin.
   *
   * @param int $eid                event id
   * @param string $cancel_message  (Optional) message to send to members of
   *                                the event about why it is cancelled
   *
   * @return bool  true if successful
   */
  public function &events_cancel($eid, $cancel_message='') {
    return $this->call_method('facebook.events.cancel',
        array('eid' => $eid,
              'cancel_message' => $cancel_message));
  }

  /**
   * Creates an event on behalf of the user is there is a session, otherwise on
   * behalf of app.  Successful creation guarantees app will be admin.
   *
   * @param assoc array $event_info  json encoded event information
   *
   * @return int  event id
   */
  public function &events_create($event_info) {
    return $this->call_method('facebook.events.create',
        array('event_info' => $event_info));
  }

  /**
   * Edits an existing event. Only works for events where application is admin.
   *
   * @param int $eid                 event id
   * @param assoc array $event_info  json encoded event information
   *
   * @return bool  true if successful
   */
  public function &events_edit($eid, $event_info) {
    return $this->call_method('facebook.events.edit',
        array('eid' => $eid,
              'event_info' => $event_info));
  }

  /**
   * Fetches and re-caches the image stored at the given URL, for use in images
   * published to non-canvas pages via the API (for example, to user profiles
   * via profile.setFBML, or to News Feed via feed.publishUserAction).
   *
   * @param string $url  The absolute URL from which to refresh the image.
   *
   * @return bool  true on success
   */
  public function &fbml_refreshImgSrc($url) {
    return $this->call_method('facebook.fbml.refreshImgSrc',
        array('url' => $url));
  }

  /**
   * Fetches and re-caches the content stored at the given URL, for use in an
   * fb:ref FBML tag.
   *
   * @param string $url  The absolute URL from which to fetch content. This URL
   *                     should be used in a fb:ref FBML tag.
   *
   * @return bool  true on success
   */
  public function &fbml_refreshRefUrl($url) {
    return $this->call_method('facebook.fbml.refreshRefUrl',
        array('url' => $url));
  }

  /**
   * Lets you insert text strings in their native language into the Facebook
   * Translations database so they can be translated.
   *
   * @param array $native_strings  An array of maps, where each map has a 'text'
   *                               field and a 'description' field.
   *
   * @return int  Number of strings uploaded.
   */
  public function &fbml_uploadNativeStrings($native_strings) {
    return $this->call_method('facebook.fbml.uploadNativeStrings',
        array('native_strings' => json_encode($native_strings)));
  }

  /**
   * Associates a given "handle" with FBML markup so that the handle can be
   * used within the fb:ref FBML tag. A handle is unique within an application
   * and allows an application to publish identical FBML to many user profiles
   * and do subsequent updates without having to republish FBML on behalf of
   * each user.
   *
   * @param string $handle  The handle to associate with the given FBML.
   * @param string $fbml    The FBML to associate with the given handle.
   *
   * @return bool  true on success
   */
  public function &fbml_setRefHandle($handle, $fbml) {
    return $this->call_method('facebook.fbml.setRefHandle',
        array('handle' => $handle, 'fbml' => $fbml));
  }

  /**
   * Register custom tags for the application. Custom tags can be used
   * to extend the set of tags available to applications in FBML
   * markup.
   *
   * Before you call this function,
   * make sure you read the full documentation at
   *
   * http://wiki.developers.facebook.com/index.php/Fbml.RegisterCustomTags
   *
   * IMPORTANT: This function overwrites the values of
   * existing tags if the names match. Use this function with care because
   * it may break the FBML of any application that is using the
   * existing version of the tags.
   *
   * @param mixed $tags an array of tag objects (the full description is on the
   *   wiki page)
   *
   * @return int  the number of tags that were registered
   */
  public function &fbml_registerCustomTags($tags) {
    $tags = json_encode($tags);
    return $this->call_method('facebook.fbml.registerCustomTags',
                              array('tags' => $tags));
  }

  /**
   * Get the custom tags for an application. If $app_id
   * is not specified, the calling app's tags are returned.
   * If $app_id is different from the id of the calling app,
   * only the app's public tags are returned.
   * The return value is an array of the same type as
   * the $tags parameter of fbml_registerCustomTags().
   *
   * @param int $app_id the application's id (optional)
   *
   * @return mixed  an array containing the custom tag  objects
   */
  public function &fbml_getCustomTags($app_id = null) {
    return $this->call_method('facebook.fbml.getCustomTags',
                              array('app_id' => $app_id));
  }


  /**
   * Delete custom tags the application has registered. If
   * $tag_names is null, all the application's custom tags will be
   * deleted.
   *
   * IMPORTANT: If your application has registered public tags
   * that other applications may be using, don't delete those tags!
   * Doing so can break the FBML ofapplications that are using them.
   *
   * @param array $tag_names the names of the tags to delete (optinal)
   * @return bool true on success
   */
  public function &fbml_deleteCustomTags($tag_names = null) {
    return $this->call_method('facebook.fbml.deleteCustomTags',
                              array('tag_names' => json_encode($tag_names)));
  }



  /**
   * This method is deprecated for calls made on behalf of users. This method
   * works only for publishing stories on a Facebook Page that has installed
   * your application. To publish stories to a user's profile, use
   * feed.publishUserAction instead.
   *
   * For more details on this call, please visit the wiki page:
   *
   * http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction
   */
  public function &feed_publishTemplatizedAction($title_template,
                                                 $title_data,
                                                 $body_template,
                                                 $body_data,
                                                 $body_general,
                                                 $image_1=null,
                                                 $image_1_link=null,
                                                 $image_2=null,
                                                 $image_2_link=null,
                                                 $image_3=null,
                                                 $image_3_link=null,
                                                 $image_4=null,
                                                 $image_4_link=null,
                                                 $target_ids='',
                                                 $page_actor_id=null) {
    return $this->call_method('facebook.feed.publishTemplatizedAction',
      array('title_template' => $title_template,
            'title_data' => $title_data,
            'body_template' => $body_template,
            'body_data' => $body_data,
            'body_general' => $body_general,
            'image_1' => $image_1,
            'image_1_link' => $image_1_link,
            'image_2' => $image_2,
            'image_2_link' => $image_2_link,
            'image_3' => $image_3,
            'image_3_link' => $image_3_link,
            'image_4' => $image_4,
            'image_4_link' => $image_4_link,
            'target_ids' => $target_ids,
            'page_actor_id' => $page_actor_id));
  }

  /**
   * Registers a template bundle.  Template bundles are somewhat involved, so
   * it's recommended you check out the wiki for more details:
   *
   *  http://wiki.developers.facebook.com/index.php/Feed.registerTemplateBundle
   *
   * @return string  A template bundle id
   */
  public function &feed_registerTemplateBundle($one_line_story_templates,
                                               $short_story_templates = array(),
                                               $full_story_template = null,
                                               $action_links = array()) {

    $one_line_story_templates = json_encode($one_line_story_templates);

    if (!empty($short_story_templates)) {
      $short_story_templates = json_encode($short_story_templates);
    }

    if (isset($full_story_template)) {
      $full_story_template = json_encode($full_story_template);
    }

    if (isset($action_links)) {
      $action_links = json_encode($action_links);
    }

    return $this->call_method('facebook.feed.registerTemplateBundle',
        array('one_line_story_templates' => $one_line_story_templates,
              'short_story_templates' => $short_story_templates,
              'full_story_template' => $full_story_template,
              'action_links' => $action_links));
  }

  /**
   * Retrieves the full list of active template bundles registered by the
   * requesting application.
   *
   * @return array  An array of template bundles
   */
  public function &feed_getRegisteredTemplateBundles() {
    return $this->call_method('facebook.feed.getRegisteredTemplateBundles',
        array());
  }

  /**
   * Retrieves information about a specified template bundle previously
   * registered by the requesting application.
   *
   * @param string $template_bundle_id  The template bundle id
   *
   * @return array  Template bundle
   */
  public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
    return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
        array('template_bundle_id' => $template_bundle_id));
  }

  /**
   * Deactivates a previously registered template bundle.
   *
   * @param string $template_bundle_id  The template bundle id
   *
   * @return bool  true on success
   */
  public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
    return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
        array('template_bundle_id' => $template_bundle_id));
  }

  const STORY_SIZE_ONE_LINE = 1;
  const STORY_SIZE_SHORT = 2;
  const STORY_SIZE_FULL = 4;

  /**
   * Publishes a story on behalf of the user owning the session, using the
   * specified template bundle. This method requires an active session key in
   * order to be called.
   *
   * The parameters to this method ($templata_data in particular) are somewhat
   * involved.  It's recommended you visit the wiki for details:
   *
   *  http://wiki.developers.facebook.com/index.php/Feed.publishUserAction
   *
   * @param int $template_bundle_id  A template bundle id previously registered
   * @param array $template_data     See wiki article for syntax
   * @param array $target_ids        (Optional) An array of friend uids of the
   *                                 user who shared in this action.
   * @param string $body_general     (Optional) Additional markup that extends
   *                                 the body of a short story.
   * @param int $story_size          (Optional) A story size (see above)
   * @param string $user_message     (Optional) A user message for a short
   *                                 story.
   *
   * @return bool  true on success
   */
  public function &feed_publishUserAction(
      $template_bundle_id, $template_data, $target_ids='', $body_general='',
      $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE,
      $user_message='') {

    if (is_array($template_data)) {
      $template_data = json_encode($template_data);
    } // allow client to either pass in JSON or an assoc that we JSON for them

    if (is_array($target_ids)) {
      $target_ids = json_encode($target_ids);
      $target_ids = trim($target_ids, "[]"); // we don't want square brackets
    }

    return $this->call_method('facebook.feed.publishUserAction',
        array('template_bundle_id' => $template_bundle_id,
              'template_data' => $template_data,
              'target_ids' => $target_ids,
              'body_general' => $body_general,
              'story_size' => $story_size,
              'user_message' => $user_message));
  }


  /**
   * Publish a post to the user's stream.
   *
   * @param $message        the user's message
   * @param $attachment     the post's attachment (optional)
   * @param $action links   the post's action links (optional)
   * @param $target_id      the user on whose wall the post will be posted
   *                        (optional)
   * @param $uid            the actor (defaults to session user)
   * @return string the post id
   */
  public function stream_publish(
    $message, $attachment = null, $action_links = null, $target_id = null,
    $uid = null) {

    return $this->call_method(
      'facebook.stream.publish',
      array('message' => $message,
            'attachment' => $attachment,
            'action_links' => $action_links,
            'target_id' => $target_id,
            'uid' => $this->get_uid($uid)));
  }

  /**
   * Remove a post from the user's stream.
   * Currently, you may only remove stories you application created.
   *
   * @param $post_id  the post id
   * @param $uid      the actor (defaults to session user)
   * @return bool
   */
  public function stream_remove($post_id, $uid = null) {
    return $this->call_method(
      'facebook.stream.remove',
      array('post_id' => $post_id,
            'uid' => $this->get_uid($uid)));
  }

  /**
   * Add a comment to a stream post
   *
   * @param $post_id  the post id
   * @param $comment  the comment text
   * @param $uid      the actor (defaults to session user)
   * @return string the id of the created comment
   */
  public function stream_addComment($post_id, $comment, $uid = null) {
    return $this->call_method(
      'facebook.stream.addComment',
      array('post_id' => $post_id,
            'comment' => $comment,
            'uid' => $this->get_uid($uid)));
  }


  /**
   * Remove a comment from a stream post
   *
   * @param $comment_id  the comment id
   * @param $uid      the actor (defaults to session user)
   * @return bool
   */
  public function stream_removeComment($comment_id, $uid = null) {
    return $this->call_method(
      'facebook.stream.removeComment',
      array('comment_id' => $comment_id,
            'uid' => $this->get_uid($uid)));
  }

  /**
   * Add a like to a stream post
   *
   * @param $post_id  the post id
   * @param $uid      the actor (defaults to session user)
   * @return bool
   */
  public function stream_addLike($post_id, $uid = null) {
    return $this->call_method(
      'facebook.stream.addLike',
      array('post_id' => $post_id,
            'uid' => $this->get_uid($uid)));
  }

  /**
   * Remove a like from a stream post
   *
   * @param $post_id  the post id
   * @param $uid      the actor (defaults to session user)
   * @return bool
   */
  public function stream_removeLike($post_id, $uid = null) {
    return $this->call_method(
      'facebook.stream.removeLike',
      array('post_id' => $post_id,
            'uid' => $this->get_uid($uid)));
  }

  /**
   * For the current user, retrieves stories generated by the user's friends
   * while using this application.  This can be used to easily create a
   * "News Feed" like experience.
   *
   * @return array  An array of feed story objects.
   */
  public function &feed_getAppFriendStories() {
    return $this->call_method('facebook.feed.getAppFriendStories');
  }

  /**
   * Makes an FQL query.  This is a generalized way of accessing all the data
   * in the API, as an alternative to most of the other method calls.  More
   * info at http://developers.facebook.com/documentation.php?v=1.0&doc=fql
   *
   * @param string $query  the query to evaluate
   *
   * @return array  generalized array representing the results
   */
  public function &fql_query($query) {
    return $this->call_method('facebook.fql.query',
      array('query' => $query));
  }

  /**
   * Returns whether or not pairs of users are friends.
   * Note that the Facebook friend relationship is symmetric.
   *
   * @param array/string $uids1  list of ids (id_1, id_2,...)
   *                       of some length X (csv is deprecated)
   * @param array/string $uids2  list of ids (id_A, id_B,...)
   *                       of SAME length X (csv is deprecated)
   *
   * @return array  An array with uid1, uid2, and bool if friends, e.g.:
   *   array(0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1),
   *         1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0)
   *         ...)
   * @error
   *    API_EC_PARAM_USER_ID_LIST
   */
  public function &friends_areFriends($uids1, $uids2) {
    return $this->call_method('facebook.friends.areFriends',
                 array('uids1' => $uids1,
                       'uids2' => $uids2));
  }

  /**
   * Returns the friends of the current session user.
   *
   * @param int $flid  (Optional) Only return friends on this friend list.
   * @param int $uid   (Optional) Return friends for this user.
   *
   * @return array  An array of friends
   */
  public function &friends_get($flid=null, $uid = null) {
    if (isset($this->friends_list)) {
      return $this->friends_list;
    }
    $params = array();
    if (!$uid && isset($this->canvas_user)) {
      $uid = $this->canvas_user;
    }
    if ($uid) {
      $params['uid'] = $uid;
    }
    if ($flid) {
      $params['flid'] = $flid;
    }
    return $this->call_method('facebook.friends.get', $params);

  }

  /**
   * Returns the set of friend lists for the current session user.
   *
   * @return array  An array of friend list objects
   */
  public function &friends_getLists() {
    return $this->call_method('facebook.friends.getLists');
  }

  /**
   * Returns the friends of the session user, who are also users
   * of the calling application.
   *
   * @return array  An array of friends also using the app
   */
  public function &friends_getAppUsers() {
    return $this->call_method('facebook.friends.getAppUsers');
  }

  /**
   * Returns groups according to the filters specified.
   *
   * @param int $uid     (Optional) User associated with groups.  A null
   *                     parameter will default to the session user.
   * @param array/string $gids (Optional) Array of group ids to query. A null
   *                     parameter will get all groups for the user.
   *                     (csv is deprecated)
   *
   * @return array  An array of group objects
   */
  public function &groups_get($uid, $gids) {
    return $this->call_method('facebook.groups.get',
        array('uid' => $uid,
              'gids' => $gids));
  }

  /**
   * Returns the membership list of a group.
   *
   * @param int $gid  Group id
   *
   * @return array  An array with four membership lists, with keys 'members',
   *                'admins', 'officers', and 'not_replied'
   */
  public function &groups_getMembers($gid) {
    return $this->call_method('facebook.groups.getMembers',
      array('gid' => $gid));
  }

  /**
   * Returns cookies according to the filters specified.
   *
   * @param int $uid     User for which the cookies are needed.
   * @param string $name (Optional) A null parameter will get all cookies
   *                     for the user.
   *
   * @return array  Cookies!  Nom nom nom nom nom.
   */
  public function data_getCookies($uid, $name) {
    return $this->call_method('facebook.data.getCookies',
        array('uid' => $uid,
              'name' => $name));
  }

  /**
   * Sets cookies according to the params specified.
   *
   * @param int $uid       User for which the cookies are needed.
   * @param string $name   Name of the cookie
   * @param string $value  (Optional) if expires specified and is in the past
   * @param int $expires   (Optional) Expiry time
   * @param string $path   (Optional) Url path to associate with (default is /)
   *
   * @return bool  true on success
   */
  public function data_setCookie($uid, $name, $value, $expires, $path) {
    return $this->call_method('facebook.data.setCookie',
        array('uid' => $uid,
              'name' => $name,
              'value' => $value,
              'expires' => $expires,
              'path' => $path));
  }

  /**
   * Retrieves links posted by the given user.
   *
   * @param int    $uid      The user whose links you wish to retrieve
   * @param int    $limit    The maximimum number of links to retrieve
   * @param array $link_ids (Optional) Array of specific link
   *                          IDs to retrieve by this user
   *
   * @return array  An array of links.
   */
  public function &links_get($uid, $limit, $link_ids = null) {
    return $this->call_method('links.get',
        array('uid' => $uid,
              'limit' => $limit,
              'link_ids' => $link_ids));
  }

  /**
   * Posts a link on Facebook.
   *
   * @param string $url     URL/link you wish to post
   * @param string $comment (Optional) A comment about this link
   * @param int    $uid     (Optional) User ID that is posting this link;
   *                        defaults to current session user
   *
   * @return bool
   */
  public function &links_post($url, $comment='', $uid = null) {
    return $this->call_method('links.post',
        array('uid' => $uid,
              'url' => $url,
              'comment' => $comment));
  }

  /**
   * Permissions API
   */

  /**
   * Checks API-access granted by self to the specified application.
   *
   * @param string $permissions_apikey  Other application key
   *
   * @return array  API methods/namespaces which are allowed access
   */
  public function permissions_checkGrantedApiAccess($permissions_apikey) {
    return $this->call_method('facebook.permissions.checkGrantedApiAccess',
        array('permissions_apikey' => $permissions_apikey));
  }

  /**
   * Checks API-access granted to self by the specified application.
   *
   * @param string $permissions_apikey  Other application key
   *
   * @return array  API methods/namespaces which are allowed access
   */
  public function permissions_checkAvailableApiAccess($permissions_apikey) {
    return $this->call_method('facebook.permissions.checkAvailableApiAccess',
        array('permissions_apikey' => $permissions_apikey));
  }

  /**
   * Grant API-access to the specified methods/namespaces to the specified
   * application.
   *
   * @param string $permissions_apikey  Other application key
   * @param array(string) $method_arr   (Optional) API methods/namespaces
   *                                    allowed
   *
   * @return array  API methods/namespaces which are allowed access
   */
  public function permissions_grantApiAccess($permissions_apikey, $method_arr) {
    return $this->call_method('facebook.permissions.grantApiAccess',
        array('permissions_apikey' => $permissions_apikey,
              'method_arr' => $method_arr));
  }

  /**
   * Revoke API-access granted to the specified application.
   *
   * @param string $permissions_apikey  Other application key
   *
   * @return bool  true on success
   */
  public function permissions_revokeApiAccess($permissions_apikey) {
    return $this->call_method('facebook.permissions.revokeApiAccess',
        array('permissions_apikey' => $permissions_apikey));
  }

  /**
   * Creates a note with the specified title and content.
   *
   * @param string $title   Title of the note.
   * @param string $content Content of the note.
   * @param int    $uid     (Optional) The user for whom you are creating a
   *                        note; defaults to current session user
   *
   * @return int   The ID of the note that was just created.
   */
  public function &notes_create($title, $content, $uid = null) {
    return $this->call_method('notes.create',
        array('uid' => $uid,
              'title' => $title,
              'content' => $content));
  }

  /**
   * Deletes the specified note.
   *
   * @param int $note_id  ID of the note you wish to delete
   * @param int $uid      (Optional) Owner of the note you wish to delete;
   *                      defaults to current session user
   *
   * @return bool
   */
  public function &notes_delete($note_id, $uid = null) {
    return $this->call_method('notes.delete',
        array('uid' => $uid,
              'note_id' => $note_id));
  }

  /**
   * Edits a note, replacing its title and contents with the title
   * and contents specified.
   *
   * @param int    $note_id  ID of the note you wish to edit
   * @param string $title    Replacement title for the note
   * @param string $content  Replacement content for the note
   * @param int    $uid      (Optional) Owner of the note you wish to edit;
   *                         defaults to current session user
   *
   * @return bool
   */
  public function &notes_edit($note_id, $title, $content, $uid = null) {
    return $this->call_method('notes.edit',
        array('uid' => $uid,
              'note_id' => $note_id,
              'title' => $title,
              'content' => $content));
  }

  /**
   * Retrieves all notes by a user. If note_ids are specified,
   * retrieves only those specific notes by that user.
   *
   * @param int    $uid      User whose notes you wish to retrieve
   * @param array  $note_ids (Optional) List of specific note
   *                         IDs by this user to retrieve
   *
   * @return array A list of all of the given user's notes, or an empty list
   *               if the viewer lacks permissions or if there are no visible
   *               notes.
   */
  public function &notes_get($uid, $note_ids = null) {

    return $this->call_method('notes.get',
        array('uid' => $uid,
              'note_ids' => $note_ids));
  }


  /**
   * Returns the outstanding notifications for the session user.
   *
   * @return array An assoc array of notification count objects for
   *               'messages', 'pokes' and 'shares', a uid list of
   *               'friend_requests', a gid list of 'group_invites',
   *               and an eid list of 'event_invites'
   */
  public function &notifications_get() {
    return $this->call_method('facebook.notifications.get');
  }

  /**
   * Sends a notification to the specified users.
   *
   * @return A comma separated list of successful recipients
   * @error
   *    API_EC_PARAM_USER_ID_LIST
   */
  public function &notifications_send($to_ids, $notification, $type) {
    return $this->call_method('facebook.notifications.send',
        array('to_ids' => $to_ids,
              'notification' => $notification,
              'type' => $type));
  }

  /**
   * Sends an email to the specified user of the application.
   *
   * @param array/string $recipients array of ids of the recipients (csv is deprecated)
   * @param string $subject    subject of the email
   * @param string $text       (plain text) body of the email
   * @param string $fbml       fbml markup for an html version of the email
   *
   * @return string  A comma separated list of successful recipients
   * @error
   *    API_EC_PARAM_USER_ID_LIST
   */
  public function &notifications_sendEmail($recipients,
                                           $subject,
                                           $text,
                                           $fbml) {
    return $this->call_method('facebook.notifications.sendEmail',
        array('recipients' => $recipients,
              'subject' => $subject,
              'text' => $text,
              'fbml' => $fbml));
  }

  /**
   * Returns the requested info fields for the requested set of pages.
   *
   * @param array/string $page_ids  an array of page ids (csv is deprecated)
   * @param array/string  $fields    an array of strings describing the
   *                           info fields desired (csv is deprecated)
   * @param int    $uid       (Optional) limit results to pages of which this
   *                          user is a fan.
   * @param string type       limits results to a particular type of page.
   *
   * @return array  An array of pages
   */
  public function &pages_getInfo($page_ids, $fields, $uid, $type) {
    return $this->call_method('facebook.pages.getInfo',
        array('page_ids' => $page_ids,
              'fields' => $fields,
              'uid' => $uid,
              'type' => $type));
  }

  /**
   * Returns true if the given user is an admin for the passed page.
   *
   * @param int $page_id  target page id
   * @param int $uid      (Optional) user id (defaults to the logged-in user)
   *
   * @return bool  true on success
   */
  public function &pages_isAdmin($page_id, $uid = null) {
    return $this->call_method('facebook.pages.isAdmin',
        array('page_id' => $page_id,
              'uid' => $uid));
  }

  /**
   * Returns whether or not the given page has added the application.
   *
   * @param int $page_id  target page id
   *
   * @return bool  true on success
   */
  public function &pages_isAppAdded($page_id) {
    return $this->call_method('facebook.pages.isAppAdded',
        array('page_id' => $page_id));
  }

  /**
   * Returns true if logged in user is a fan for the passed page.
   *
   * @param int $page_id target page id
   * @param int $uid user to compare.  If empty, the logged in user.
   *
   * @return bool  true on success
   */
  public function &pages_isFan($page_id, $uid = null) {
    return $this->call_method('facebook.pages.isFan',
        array('page_id' => $page_id,
              'uid' => $uid));
  }

  /**
   * Adds a tag with the given information to a photo. See the wiki for details:
   *
   *  http://wiki.developers.facebook.com/index.php/Photos.addTag
   *
   * @param int $pid          The ID of the photo to be tagged
   * @param int $tag_uid      The ID of the user being tagged. You must specify
   *                          either the $tag_uid or the $tag_text parameter
   *                          (unless $tags is specified).
   * @param string $tag_text  Some text identifying the person being tagged.
   *                          You must specify either the $tag_uid or $tag_text
   *                          parameter (unless $tags is specified).
   * @param float $x          The horizontal position of the tag, as a
   *                          percentage from 0 to 100, from the left of the
   *                          photo.
   * @param float $y  …

Large files files are truncated, but you can click here to view the full file