2 // Copyright 2004-2009 Facebook. All Rights Reserved.
4 // +---------------------------------------------------------------------------+
5 // | Facebook Platform PHP5 client |
6 // +---------------------------------------------------------------------------+
7 // | Copyright (c) 2007-2009 Facebook, Inc. |
8 // | All rights reserved. |
10 // | Redistribution and use in source and binary forms, with or without |
11 // | modification, are permitted provided that the following conditions |
14 // | 1. Redistributions of source code must retain the above copyright |
15 // | notice, this list of conditions and the following disclaimer. |
16 // | 2. Redistributions in binary form must reproduce the above copyright |
17 // | notice, this list of conditions and the following disclaimer in the |
18 // | documentation and/or other materials provided with the distribution. |
20 // | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
21 // | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
22 // | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
23 // | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
24 // | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
25 // | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
26 // | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
27 // | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
28 // | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
29 // | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
30 // +---------------------------------------------------------------------------+
31 // | For help with this library, contact developers-help@facebook.com |
32 // +---------------------------------------------------------------------------+
35 include_once 'jsonwrapper/jsonwrapper.php';
37 class FacebookRestClient {
41 // to save making the friends.get api call, this will get prepopulated on
45 // to save making the pages.isAppAdded api call, this will get prepopulated
49 // we don't pass friends list to iframes, but we want to make
50 // friends_get really simple in the canvas_user (non-logged in) case.
51 // So we use the canvas_user as default arg to friends_get
55 private $pending_batch;
56 private $call_as_apikey;
57 private $use_curl_if_available;
58 private $format = null;
60 const BATCH_MODE_DEFAULT = 0;
61 const BATCH_MODE_SERVER_PARALLEL = 0;
62 const BATCH_MODE_SERIAL_ONLY = 2;
66 * @param string $session_key if you haven't gotten a session key yet, leave
67 * this as null and then set it later by just
68 * directly accessing the $session_key member
71 public function __construct($api_key, $secret, $session_key=null) {
72 $this->secret = $secret;
73 $this->session_key = $session_key;
74 $this->api_key = $api_key;
75 $this->batch_mode = FacebookRestClient::BATCH_MODE_DEFAULT;
76 $this->last_call_id = 0;
77 $this->call_as_apikey = '';
78 $this->use_curl_if_available = true;
79 $this->server_addr = Facebook::get_facebook_url('api') . '/restserver.php';
81 if (!empty($GLOBALS['facebook_config']['debug'])) {
84 <script type="text/javascript">
85 var types = ['params', 'xml', 'php', 'sxml'];
86 function getStyle(elem, style) {
88 return elem.getStyle(style);
90 return elem.style[style];
93 function setStyle(elem, style, value) {
95 elem.setStyle(style, value);
97 elem.style[style] = value;
100 function toggleDisplay(id, type) {
101 for (var i = 0; i < types.length; i++) {
103 var pre = document.getElementById(t + id);
105 if (t != type || getStyle(pre, 'display') == 'block') {
106 setStyle(pre, 'display', 'none');
108 setStyle(pre, 'display', 'block');
120 * Set the default user id for methods that allow the caller
121 * to pass an uid parameter to identify the target user
122 * instead of a session key. This currently applies to
123 * the user preferences methods.
125 * @param $uid int the user id
127 public function set_user($uid) {
132 * Normally, if the cURL library/PHP extension is available, it is used for
133 * HTTP transactions. This allows that behavior to be overridden, falling
134 * back to a vanilla-PHP implementation even if cURL is installed.
136 * @param $use_curl_if_available bool whether or not to use cURL if available
138 public function set_use_curl_if_available($use_curl_if_available) {
139 $this->use_curl_if_available = $use_curl_if_available;
143 * Start a batch operation.
145 public function begin_batch() {
146 if ($this->pending_batch()) {
147 $code = FacebookAPIErrorCodes::API_EC_BATCH_ALREADY_STARTED;
148 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
149 throw new FacebookRestClientException($description, $code);
152 $this->batch_queue = array();
153 $this->pending_batch = true;
157 * End current batch operation
159 public function end_batch() {
160 if (!$this->pending_batch()) {
161 $code = FacebookAPIErrorCodes::API_EC_BATCH_NOT_STARTED;
162 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
163 throw new FacebookRestClientException($description, $code);
166 $this->pending_batch = false;
168 $this->execute_server_side_batch();
169 $this->batch_queue = null;
173 * are we currently queueing up calls for a batch?
175 public function pending_batch() {
176 return $this->pending_batch;
179 private function execute_server_side_batch() {
180 $item_count = count($this->batch_queue);
181 $method_feed = array();
182 foreach ($this->batch_queue as $batch_item) {
183 $method = $batch_item['m'];
184 $params = $batch_item['p'];
185 list($get, $post) = $this->finalize_params($method, $params);
186 $method_feed[] = $this->create_url_string(array_merge($post, $get));
190 ($this->batch_mode == FacebookRestClient::BATCH_MODE_SERIAL_ONLY);
192 $params = array('method_feed' => json_encode($method_feed),
193 'serial_only' => $serial_only,
194 'format' => $this->format);
195 $result = $this->call_method('facebook.batch.run', $params);
197 if (is_array($result) && isset($result['error_code'])) {
198 throw new FacebookRestClientException($result['error_msg'],
199 $result['error_code']);
202 for ($i = 0; $i < $item_count; $i++) {
203 $batch_item = $this->batch_queue[$i];
204 $batch_item['p']['format'] = $this->format;
205 $batch_item_result = $this->convert_result($result[$i],
209 if (is_array($batch_item_result) &&
210 isset($batch_item_result['error_code'])) {
211 throw new FacebookRestClientException($batch_item_result['error_msg'],
212 $batch_item_result['error_code']);
214 $batch_item['r'] = $batch_item_result;
218 public function begin_permissions_mode($permissions_apikey) {
219 $this->call_as_apikey = $permissions_apikey;
222 public function end_permissions_mode() {
223 $this->call_as_apikey = '';
228 * If a page is loaded via HTTPS, then all images and static
229 * resources need to be printed with HTTPS urls to avoid
230 * mixed content warnings. If your page loads with an HTTPS
231 * url, then call set_use_ssl_resources to retrieve the correct
234 public function set_use_ssl_resources($is_ssl = true) {
235 $this->use_ssl_resources = $is_ssl;
239 * Returns public information for an application (as shown in the application
240 * directory) by either application ID, API key, or canvas page name.
242 * @param int $application_id (Optional) app id
243 * @param string $application_api_key (Optional) api key
244 * @param string $application_canvas_name (Optional) canvas name
246 * Exactly one argument must be specified, otherwise it is an error.
248 * @return array An array of public information about the application.
250 public function application_getPublicInfo($application_id=null,
251 $application_api_key=null,
252 $application_canvas_name=null) {
253 return $this->call_method('facebook.application.getPublicInfo',
254 array('application_id' => $application_id,
255 'application_api_key' => $application_api_key,
256 'application_canvas_name' => $application_canvas_name));
260 * Creates an authentication token to be used as part of the desktop login
261 * flow. For more information, please see
262 * http://wiki.developers.facebook.com/index.php/Auth.createToken.
264 * @return string An authentication token.
266 public function auth_createToken() {
267 return $this->call_method('facebook.auth.createToken');
271 * Returns the session information available after current user logs in.
273 * @param string $auth_token the token returned by
274 * auth_createToken or passed back to
276 * @param bool $generate_session_secret whether the session returned should
277 * include a session secret
279 * @return array An assoc array containing session_key, uid
281 public function auth_getSession($auth_token, $generate_session_secret=false) {
282 if (!$this->pending_batch()) {
283 $result = $this->call_method('facebook.auth.getSession',
284 array('auth_token' => $auth_token,
285 'generate_session_secret' => $generate_session_secret));
286 $this->session_key = $result['session_key'];
288 if (!empty($result['secret']) && !$generate_session_secret) {
289 // desktop apps have a special secret
290 $this->secret = $result['secret'];
297 * Generates a session-specific secret. This is for integration with
298 * client-side API calls, such as the JS library.
300 * @return array A session secret for the current promoted session
302 * @error API_EC_PARAM_SESSION_KEY
303 * API_EC_PARAM_UNKNOWN
305 public function auth_promoteSession() {
306 return $this->call_method('facebook.auth.promoteSession');
310 * Expires the session that is currently being used. If this call is
311 * successful, no further calls to the API (which require a session) can be
312 * made until a valid session is created.
314 * @return bool true if session expiration was successful, false otherwise
316 public function auth_expireSession() {
317 return $this->call_method('facebook.auth.expireSession');
321 * Revokes the given extended permission that the user granted at some
322 * prior time (for instance, offline_access or email). If no user is
323 * provided, it will be revoked for the user of the current session.
325 * @param string $perm The permission to revoke
326 * @param int $uid The user for whom to revoke the permission.
328 public function auth_revokeExtendedPermission($perm, $uid=null) {
329 return $this->call_method('facebook.auth.revokeExtendedPermission',
330 array('perm' => $perm, 'uid' => $uid));
334 * Revokes the user's agreement to the Facebook Terms of Service for your
335 * application. If you call this method for one of your users, you will no
336 * longer be able to make API requests on their behalf until they again
337 * authorize your application. Use with care. Note that if this method is
338 * called without a user parameter, then it will revoke access for the
339 * current session's user.
341 * @param int $uid (Optional) User to revoke
343 * @return bool true if revocation succeeds, false otherwise
345 public function auth_revokeAuthorization($uid=null) {
346 return $this->call_method('facebook.auth.revokeAuthorization',
347 array('uid' => $uid));
351 * Get public key that is needed to verify digital signature
352 * an app may pass to other apps. The public key is only used by
353 * other apps for verification purposes.
354 * @param string API key of an app
355 * @return string The public key for the app.
357 public function auth_getAppPublicKey($target_app_key) {
358 return $this->call_method('facebook.auth.getAppPublicKey',
359 array('target_app_key' => $target_app_key));
363 * Get a structure that can be passed to another app
364 * as proof of session. The other app can verify it using public
367 * @return signed public session data structure.
369 public function auth_getSignedPublicSessionData() {
370 return $this->call_method('facebook.auth.getSignedPublicSessionData',
375 * Returns the number of unconnected friends that exist in this application.
376 * This number is determined based on the accounts registered through
377 * connect.registerUsers() (see below).
379 public function connect_getUnconnectedFriendsCount() {
380 return $this->call_method('facebook.connect.getUnconnectedFriendsCount',
385 * This method is used to create an association between an external user
386 * account and a Facebook user account, as per Facebook Connect.
388 * This method takes an array of account data, including a required email_hash
389 * and optional account data. For each connected account, if the user exists,
390 * the information is added to the set of the user's connected accounts.
391 * If the user has already authorized the site, the connected account is added
392 * in the confirmed state. If the user has not yet authorized the site, the
393 * connected account is added in the pending state.
395 * This is designed to help Facebook Connect recognize when two Facebook
396 * friends are both members of a external site, but perhaps are not aware of
397 * it. The Connect dialog (see fb:connect-form) is used when friends can be
398 * identified through these email hashes. See the following url for details:
400 * http://wiki.developers.facebook.com/index.php/Connect.registerUsers
402 * @param mixed $accounts A (JSON-encoded) array of arrays, where each array
403 * has three properties:
404 * 'email_hash' (req) - public email hash of account
405 * 'account_id' (opt) - remote account id;
406 * 'account_url' (opt) - url to remote account;
408 * @return array The list of email hashes for the successfully registered
411 public function connect_registerUsers($accounts) {
412 return $this->call_method('facebook.connect.registerUsers',
413 array('accounts' => $accounts));
417 * Unregisters a set of accounts registered using connect.registerUsers.
419 * @param array $email_hashes The (JSON-encoded) list of email hashes to be
422 * @return array The list of email hashes which have been successfully
425 public function connect_unregisterUsers($email_hashes) {
426 return $this->call_method('facebook.connect.unregisterUsers',
427 array('email_hashes' => $email_hashes));
431 * Returns events according to the filters specified.
433 * @param int $uid (Optional) User associated with events. A null
434 * parameter will default to the session user.
435 * @param array/string $eids (Optional) Filter by these event
436 * ids. A null parameter will get all events for
437 * the user. (A csv list will work but is deprecated)
438 * @param int $start_time (Optional) Filter with this unix time as lower
439 * bound. A null or zero parameter indicates no
441 * @param int $end_time (Optional) Filter with this UTC as upper bound.
442 * A null or zero parameter indicates no upper
444 * @param string $rsvp_status (Optional) Only show events where the given uid
445 * has this rsvp status. This only works if you
446 * have specified a value for $uid. Values are as
447 * in events.getMembers. Null indicates to ignore
448 * rsvp status when filtering.
450 * @return array The events matching the query.
452 public function &events_get($uid=null,
457 return $this->call_method('facebook.events.get',
460 'start_time' => $start_time,
461 'end_time' => $end_time,
462 'rsvp_status' => $rsvp_status));
466 * Returns membership list data associated with an event.
468 * @param int $eid event id
470 * @return array An assoc array of four membership lists, with keys
471 * 'attending', 'unsure', 'declined', and 'not_replied'
473 public function &events_getMembers($eid) {
474 return $this->call_method('facebook.events.getMembers',
475 array('eid' => $eid));
479 * RSVPs the current user to this event.
481 * @param int $eid event id
482 * @param string $rsvp_status 'attending', 'unsure', or 'declined'
484 * @return bool true if successful
486 public function &events_rsvp($eid, $rsvp_status) {
487 return $this->call_method('facebook.events.rsvp',
490 'rsvp_status' => $rsvp_status));
494 * Cancels an event. Only works for events where application is the admin.
496 * @param int $eid event id
497 * @param string $cancel_message (Optional) message to send to members of
498 * the event about why it is cancelled
500 * @return bool true if successful
502 public function &events_cancel($eid, $cancel_message='') {
503 return $this->call_method('facebook.events.cancel',
505 'cancel_message' => $cancel_message));
509 * Creates an event on behalf of the user is there is a session, otherwise on
510 * behalf of app. Successful creation guarantees app will be admin.
512 * @param assoc array $event_info json encoded event information
513 * @param string $file (Optional) filename of picture to set
515 * @return int event id
517 public function events_create($event_info, $file = null) {
519 return $this->call_upload_method('facebook.events.create',
520 array('event_info' => $event_info),
522 Facebook::get_facebook_url('api-photo') . '/restserver.php');
524 return $this->call_method('facebook.events.create',
525 array('event_info' => $event_info));
530 * Edits an existing event. Only works for events where application is admin.
532 * @param int $eid event id
533 * @param assoc array $event_info json encoded event information
534 * @param string $file (Optional) filename of new picture to set
536 * @return bool true if successful
538 public function events_edit($eid, $event_info, $file = null) {
540 return $this->call_upload_method('facebook.events.edit',
541 array('eid' => $eid, 'event_info' => $event_info),
543 Facebook::get_facebook_url('api-photo') . '/restserver.php');
545 return $this->call_method('facebook.events.edit',
547 'event_info' => $event_info));
552 * Fetches and re-caches the image stored at the given URL, for use in images
553 * published to non-canvas pages via the API (for example, to user profiles
554 * via profile.setFBML, or to News Feed via feed.publishUserAction).
556 * @param string $url The absolute URL from which to refresh the image.
558 * @return bool true on success
560 public function &fbml_refreshImgSrc($url) {
561 return $this->call_method('facebook.fbml.refreshImgSrc',
562 array('url' => $url));
566 * Fetches and re-caches the content stored at the given URL, for use in an
569 * @param string $url The absolute URL from which to fetch content. This URL
570 * should be used in a fb:ref FBML tag.
572 * @return bool true on success
574 public function &fbml_refreshRefUrl($url) {
575 return $this->call_method('facebook.fbml.refreshRefUrl',
576 array('url' => $url));
580 * Lets you insert text strings in their native language into the Facebook
581 * Translations database so they can be translated.
583 * @param array $native_strings An array of maps, where each map has a 'text'
584 * field and a 'description' field.
586 * @return int Number of strings uploaded.
588 public function &fbml_uploadNativeStrings($native_strings) {
589 return $this->call_method('facebook.fbml.uploadNativeStrings',
590 array('native_strings' => json_encode($native_strings)));
594 * Associates a given "handle" with FBML markup so that the handle can be
595 * used within the fb:ref FBML tag. A handle is unique within an application
596 * and allows an application to publish identical FBML to many user profiles
597 * and do subsequent updates without having to republish FBML on behalf of
600 * @param string $handle The handle to associate with the given FBML.
601 * @param string $fbml The FBML to associate with the given handle.
603 * @return bool true on success
605 public function &fbml_setRefHandle($handle, $fbml) {
606 return $this->call_method('facebook.fbml.setRefHandle',
607 array('handle' => $handle, 'fbml' => $fbml));
611 * Register custom tags for the application. Custom tags can be used
612 * to extend the set of tags available to applications in FBML
615 * Before you call this function,
616 * make sure you read the full documentation at
618 * http://wiki.developers.facebook.com/index.php/Fbml.RegisterCustomTags
620 * IMPORTANT: This function overwrites the values of
621 * existing tags if the names match. Use this function with care because
622 * it may break the FBML of any application that is using the
623 * existing version of the tags.
625 * @param mixed $tags an array of tag objects (the full description is on the
628 * @return int the number of tags that were registered
630 public function &fbml_registerCustomTags($tags) {
631 $tags = json_encode($tags);
632 return $this->call_method('facebook.fbml.registerCustomTags',
633 array('tags' => $tags));
637 * Get the custom tags for an application. If $app_id
638 * is not specified, the calling app's tags are returned.
639 * If $app_id is different from the id of the calling app,
640 * only the app's public tags are returned.
641 * The return value is an array of the same type as
642 * the $tags parameter of fbml_registerCustomTags().
644 * @param int $app_id the application's id (optional)
646 * @return mixed an array containing the custom tag objects
648 public function &fbml_getCustomTags($app_id = null) {
649 return $this->call_method('facebook.fbml.getCustomTags',
650 array('app_id' => $app_id));
655 * Delete custom tags the application has registered. If
656 * $tag_names is null, all the application's custom tags will be
659 * IMPORTANT: If your application has registered public tags
660 * that other applications may be using, don't delete those tags!
661 * Doing so can break the FBML ofapplications that are using them.
663 * @param array $tag_names the names of the tags to delete (optinal)
664 * @return bool true on success
666 public function &fbml_deleteCustomTags($tag_names = null) {
667 return $this->call_method('facebook.fbml.deleteCustomTags',
668 array('tag_names' => json_encode($tag_names)));
674 * This method is deprecated for calls made on behalf of users. This method
675 * works only for publishing stories on a Facebook Page that has installed
676 * your application. To publish stories to a user's profile, use
677 * feed.publishUserAction instead.
679 * For more details on this call, please visit the wiki page:
681 * http://wiki.developers.facebook.com/index.php/Feed.publishTemplatizedAction
683 public function &feed_publishTemplatizedAction($title_template,
697 $page_actor_id=null) {
698 return $this->call_method('facebook.feed.publishTemplatizedAction',
699 array('title_template' => $title_template,
700 'title_data' => $title_data,
701 'body_template' => $body_template,
702 'body_data' => $body_data,
703 'body_general' => $body_general,
704 'image_1' => $image_1,
705 'image_1_link' => $image_1_link,
706 'image_2' => $image_2,
707 'image_2_link' => $image_2_link,
708 'image_3' => $image_3,
709 'image_3_link' => $image_3_link,
710 'image_4' => $image_4,
711 'image_4_link' => $image_4_link,
712 'target_ids' => $target_ids,
713 'page_actor_id' => $page_actor_id));
717 * Registers a template bundle. Template bundles are somewhat involved, so
718 * it's recommended you check out the wiki for more details:
720 * http://wiki.developers.facebook.com/index.php/Feed.registerTemplateBundle
722 * @return string A template bundle id
724 public function &feed_registerTemplateBundle($one_line_story_templates,
725 $short_story_templates = array(),
726 $full_story_template = null,
727 $action_links = array()) {
729 $one_line_story_templates = json_encode($one_line_story_templates);
731 if (!empty($short_story_templates)) {
732 $short_story_templates = json_encode($short_story_templates);
735 if (isset($full_story_template)) {
736 $full_story_template = json_encode($full_story_template);
739 if (isset($action_links)) {
740 $action_links = json_encode($action_links);
743 return $this->call_method('facebook.feed.registerTemplateBundle',
744 array('one_line_story_templates' => $one_line_story_templates,
745 'short_story_templates' => $short_story_templates,
746 'full_story_template' => $full_story_template,
747 'action_links' => $action_links));
751 * Retrieves the full list of active template bundles registered by the
752 * requesting application.
754 * @return array An array of template bundles
756 public function &feed_getRegisteredTemplateBundles() {
757 return $this->call_method('facebook.feed.getRegisteredTemplateBundles',
762 * Retrieves information about a specified template bundle previously
763 * registered by the requesting application.
765 * @param string $template_bundle_id The template bundle id
767 * @return array Template bundle
769 public function &feed_getRegisteredTemplateBundleByID($template_bundle_id) {
770 return $this->call_method('facebook.feed.getRegisteredTemplateBundleByID',
771 array('template_bundle_id' => $template_bundle_id));
775 * Deactivates a previously registered template bundle.
777 * @param string $template_bundle_id The template bundle id
779 * @return bool true on success
781 public function &feed_deactivateTemplateBundleByID($template_bundle_id) {
782 return $this->call_method('facebook.feed.deactivateTemplateBundleByID',
783 array('template_bundle_id' => $template_bundle_id));
786 const STORY_SIZE_ONE_LINE = 1;
787 const STORY_SIZE_SHORT = 2;
788 const STORY_SIZE_FULL = 4;
791 * Publishes a story on behalf of the user owning the session, using the
792 * specified template bundle. This method requires an active session key in
793 * order to be called.
795 * The parameters to this method ($templata_data in particular) are somewhat
796 * involved. It's recommended you visit the wiki for details:
798 * http://wiki.developers.facebook.com/index.php/Feed.publishUserAction
800 * @param int $template_bundle_id A template bundle id previously registered
801 * @param array $template_data See wiki article for syntax
802 * @param array $target_ids (Optional) An array of friend uids of the
803 * user who shared in this action.
804 * @param string $body_general (Optional) Additional markup that extends
805 * the body of a short story.
806 * @param int $story_size (Optional) A story size (see above)
807 * @param string $user_message (Optional) A user message for a short
810 * @return bool true on success
812 public function &feed_publishUserAction(
813 $template_bundle_id, $template_data, $target_ids='', $body_general='',
814 $story_size=FacebookRestClient::STORY_SIZE_ONE_LINE,
817 if (is_array($template_data)) {
818 $template_data = json_encode($template_data);
819 } // allow client to either pass in JSON or an assoc that we JSON for them
821 if (is_array($target_ids)) {
822 $target_ids = json_encode($target_ids);
823 $target_ids = trim($target_ids, "[]"); // we don't want square brackets
826 return $this->call_method('facebook.feed.publishUserAction',
827 array('template_bundle_id' => $template_bundle_id,
828 'template_data' => $template_data,
829 'target_ids' => $target_ids,
830 'body_general' => $body_general,
831 'story_size' => $story_size,
832 'user_message' => $user_message));
837 * Publish a post to the user's stream.
839 * @param $message the user's message
840 * @param $attachment the post's attachment (optional)
841 * @param $action links the post's action links (optional)
842 * @param $target_id the user on whose wall the post will be posted
844 * @param $uid the actor (defaults to session user)
845 * @return string the post id
847 public function stream_publish(
848 $message, $attachment = null, $action_links = null, $target_id = null,
851 return $this->call_method(
852 'facebook.stream.publish',
853 array('message' => $message,
854 'attachment' => $attachment,
855 'action_links' => $action_links,
856 'target_id' => $target_id,
857 'uid' => $this->get_uid($uid)));
861 * Remove a post from the user's stream.
862 * Currently, you may only remove stories you application created.
864 * @param $post_id the post id
865 * @param $uid the actor (defaults to session user)
868 public function stream_remove($post_id, $uid = null) {
869 return $this->call_method(
870 'facebook.stream.remove',
871 array('post_id' => $post_id,
872 'uid' => $this->get_uid($uid)));
876 * Add a comment to a stream post
878 * @param $post_id the post id
879 * @param $comment the comment text
880 * @param $uid the actor (defaults to session user)
881 * @return string the id of the created comment
883 public function stream_addComment($post_id, $comment, $uid = null) {
884 return $this->call_method(
885 'facebook.stream.addComment',
886 array('post_id' => $post_id,
887 'comment' => $comment,
888 'uid' => $this->get_uid($uid)));
893 * Remove a comment from a stream post
895 * @param $comment_id the comment id
896 * @param $uid the actor (defaults to session user)
899 public function stream_removeComment($comment_id, $uid = null) {
900 return $this->call_method(
901 'facebook.stream.removeComment',
902 array('comment_id' => $comment_id,
903 'uid' => $this->get_uid($uid)));
907 * Add a like to a stream post
909 * @param $post_id the post id
910 * @param $uid the actor (defaults to session user)
913 public function stream_addLike($post_id, $uid = null) {
914 return $this->call_method(
915 'facebook.stream.addLike',
916 array('post_id' => $post_id,
917 'uid' => $this->get_uid($uid)));
921 * Remove a like from a stream post
923 * @param $post_id the post id
924 * @param $uid the actor (defaults to session user)
927 public function stream_removeLike($post_id, $uid = null) {
928 return $this->call_method(
929 'facebook.stream.removeLike',
930 array('post_id' => $post_id,
931 'uid' => $this->get_uid($uid)));
935 * For the current user, retrieves stories generated by the user's friends
936 * while using this application. This can be used to easily create a
937 * "News Feed" like experience.
939 * @return array An array of feed story objects.
941 public function &feed_getAppFriendStories() {
942 return $this->call_method('facebook.feed.getAppFriendStories');
946 * Makes an FQL query. This is a generalized way of accessing all the data
947 * in the API, as an alternative to most of the other method calls. More
948 * info at http://wiki.developers.facebook.com/index.php/FQL
950 * @param string $query the query to evaluate
952 * @return array generalized array representing the results
954 public function &fql_query($query) {
955 return $this->call_method('facebook.fql.query',
956 array('query' => $query));
960 * Makes a set of FQL queries in parallel. This method takes a dictionary
961 * of FQL queries where the keys are names for the queries. Results from
962 * one query can be used within another query to fetch additional data. More
963 * info about FQL queries at http://wiki.developers.facebook.com/index.php/FQL
965 * @param string $queries JSON-encoded dictionary of queries to evaluate
967 * @return array generalized array representing the results
969 public function &fql_multiquery($queries) {
970 return $this->call_method('facebook.fql.multiquery',
971 array('queries' => $queries));
975 * Returns whether or not pairs of users are friends.
976 * Note that the Facebook friend relationship is symmetric.
978 * @param array/string $uids1 list of ids (id_1, id_2,...)
979 * of some length X (csv is deprecated)
980 * @param array/string $uids2 list of ids (id_A, id_B,...)
981 * of SAME length X (csv is deprecated)
983 * @return array An array with uid1, uid2, and bool if friends, e.g.:
984 * array(0 => array('uid1' => id_1, 'uid2' => id_A, 'are_friends' => 1),
985 * 1 => array('uid1' => id_2, 'uid2' => id_B, 'are_friends' => 0)
988 * API_EC_PARAM_USER_ID_LIST
990 public function &friends_areFriends($uids1, $uids2) {
991 return $this->call_method('facebook.friends.areFriends',
992 array('uids1' => $uids1,
997 * Returns the friends of the current session user.
999 * @param int $flid (Optional) Only return friends on this friend list.
1000 * @param int $uid (Optional) Return friends for this user.
1002 * @return array An array of friends
1004 public function &friends_get($flid=null, $uid = null) {
1005 if (isset($this->friends_list)) {
1006 return $this->friends_list;
1009 if (!$uid && isset($this->canvas_user)) {
1010 $uid = $this->canvas_user;
1013 $params['uid'] = $uid;
1016 $params['flid'] = $flid;
1018 return $this->call_method('facebook.friends.get', $params);
1023 * Returns the mutual friends between the target uid and a source uid or
1024 * the current session user.
1026 * @param int $target_uid Target uid for which mutual friends will be found.
1027 * @param int $source_uid (optional) Source uid for which mutual friends will
1028 * be found. If no source_uid is specified,
1029 * source_id will default to the session
1031 * @return array An array of friend uids
1033 public function &friends_getMutualFriends($target_uid, $source_uid = null) {
1034 return $this->call_method('facebook.friends.getMutualFriends',
1035 array("target_uid" => $target_uid,
1036 "source_uid" => $source_uid));
1040 * Returns the set of friend lists for the current session user.
1042 * @return array An array of friend list objects
1044 public function &friends_getLists() {
1045 return $this->call_method('facebook.friends.getLists');
1049 * Returns the friends of the session user, who are also users
1050 * of the calling application.
1052 * @return array An array of friends also using the app
1054 public function &friends_getAppUsers() {
1055 return $this->call_method('facebook.friends.getAppUsers');
1059 * Returns groups according to the filters specified.
1061 * @param int $uid (Optional) User associated with groups. A null
1062 * parameter will default to the session user.
1063 * @param array/string $gids (Optional) Array of group ids to query. A null
1064 * parameter will get all groups for the user.
1065 * (csv is deprecated)
1067 * @return array An array of group objects
1069 public function &groups_get($uid, $gids) {
1070 return $this->call_method('facebook.groups.get',
1071 array('uid' => $uid,
1076 * Returns the membership list of a group.
1078 * @param int $gid Group id
1080 * @return array An array with four membership lists, with keys 'members',
1081 * 'admins', 'officers', and 'not_replied'
1083 public function &groups_getMembers($gid) {
1084 return $this->call_method('facebook.groups.getMembers',
1085 array('gid' => $gid));
1089 * Returns cookies according to the filters specified.
1091 * @param int $uid User for which the cookies are needed.
1092 * @param string $name (Optional) A null parameter will get all cookies
1095 * @return array Cookies! Nom nom nom nom nom.
1097 public function data_getCookies($uid, $name) {
1098 return $this->call_method('facebook.data.getCookies',
1099 array('uid' => $uid,
1104 * Sets cookies according to the params specified.
1106 * @param int $uid User for which the cookies are needed.
1107 * @param string $name Name of the cookie
1108 * @param string $value (Optional) if expires specified and is in the past
1109 * @param int $expires (Optional) Expiry time
1110 * @param string $path (Optional) Url path to associate with (default is /)
1112 * @return bool true on success
1114 public function data_setCookie($uid, $name, $value, $expires, $path) {
1115 return $this->call_method('facebook.data.setCookie',
1116 array('uid' => $uid,
1119 'expires' => $expires,
1124 * Retrieves links posted by the given user.
1126 * @param int $uid The user whose links you wish to retrieve
1127 * @param int $limit The maximimum number of links to retrieve
1128 * @param array $link_ids (Optional) Array of specific link
1129 * IDs to retrieve by this user
1131 * @return array An array of links.
1133 public function &links_get($uid, $limit, $link_ids = null) {
1134 return $this->call_method('links.get',
1135 array('uid' => $uid,
1137 'link_ids' => $link_ids));
1141 * Posts a link on Facebook.
1143 * @param string $url URL/link you wish to post
1144 * @param string $comment (Optional) A comment about this link
1145 * @param int $uid (Optional) User ID that is posting this link;
1146 * defaults to current session user
1150 public function &links_post($url, $comment='', $uid = null) {
1151 return $this->call_method('links.post',
1152 array('uid' => $uid,
1154 'comment' => $comment));
1162 * Checks API-access granted by self to the specified application.
1164 * @param string $permissions_apikey Other application key
1166 * @return array API methods/namespaces which are allowed access
1168 public function permissions_checkGrantedApiAccess($permissions_apikey) {
1169 return $this->call_method('facebook.permissions.checkGrantedApiAccess',
1170 array('permissions_apikey' => $permissions_apikey));
1174 * Checks API-access granted to self by the specified application.
1176 * @param string $permissions_apikey Other application key
1178 * @return array API methods/namespaces which are allowed access
1180 public function permissions_checkAvailableApiAccess($permissions_apikey) {
1181 return $this->call_method('facebook.permissions.checkAvailableApiAccess',
1182 array('permissions_apikey' => $permissions_apikey));
1186 * Grant API-access to the specified methods/namespaces to the specified
1189 * @param string $permissions_apikey Other application key
1190 * @param array(string) $method_arr (Optional) API methods/namespaces
1193 * @return array API methods/namespaces which are allowed access
1195 public function permissions_grantApiAccess($permissions_apikey, $method_arr) {
1196 return $this->call_method('facebook.permissions.grantApiAccess',
1197 array('permissions_apikey' => $permissions_apikey,
1198 'method_arr' => $method_arr));
1202 * Revoke API-access granted to the specified application.
1204 * @param string $permissions_apikey Other application key
1206 * @return bool true on success
1208 public function permissions_revokeApiAccess($permissions_apikey) {
1209 return $this->call_method('facebook.permissions.revokeApiAccess',
1210 array('permissions_apikey' => $permissions_apikey));
1214 * Payments Order API
1218 * Set Payments properties for an app.
1220 * @param properties a map from property names to values
1221 * @return true on success
1223 public function payments_setProperties($properties) {
1224 return $this->call_method ('facebook.payments.setProperties',
1225 array('properties' => json_encode($properties)));
1228 public function payments_getOrderDetails($order_id) {
1229 return json_decode($this->call_method(
1230 'facebook.payments.getOrderDetails',
1231 array('order_id' => $order_id)), true);
1234 public function payments_updateOrder($order_id, $status,
1236 return $this->call_method('facebook.payments.updateOrder',
1237 array('order_id' => $order_id,
1238 'status' => $status,
1239 'params' => json_encode($params)));
1242 public function payments_getOrders($status, $start_time,
1243 $end_time, $test_mode=false) {
1244 return json_decode($this->call_method('facebook.payments.getOrders',
1245 array('status' => $status,
1246 'start_time' => $start_time,
1247 'end_time' => $end_time,
1248 'test_mode' => $test_mode)), true);
1252 * Creates a note with the specified title and content.
1254 * @param string $title Title of the note.
1255 * @param string $content Content of the note.
1256 * @param int $uid (Optional) The user for whom you are creating a
1257 * note; defaults to current session user
1259 * @return int The ID of the note that was just created.
1261 public function ¬es_create($title, $content, $uid = null) {
1262 return $this->call_method('notes.create',
1263 array('uid' => $uid,
1265 'content' => $content));
1269 * Deletes the specified note.
1271 * @param int $note_id ID of the note you wish to delete
1272 * @param int $uid (Optional) Owner of the note you wish to delete;
1273 * defaults to current session user
1277 public function ¬es_delete($note_id, $uid = null) {
1278 return $this->call_method('notes.delete',
1279 array('uid' => $uid,
1280 'note_id' => $note_id));
1284 * Edits a note, replacing its title and contents with the title
1285 * and contents specified.
1287 * @param int $note_id ID of the note you wish to edit
1288 * @param string $title Replacement title for the note
1289 * @param string $content Replacement content for the note
1290 * @param int $uid (Optional) Owner of the note you wish to edit;
1291 * defaults to current session user
1295 public function ¬es_edit($note_id, $title, $content, $uid = null) {
1296 return $this->call_method('notes.edit',
1297 array('uid' => $uid,
1298 'note_id' => $note_id,
1300 'content' => $content));
1304 * Retrieves all notes by a user. If note_ids are specified,
1305 * retrieves only those specific notes by that user.
1307 * @param int $uid User whose notes you wish to retrieve
1308 * @param array $note_ids (Optional) List of specific note
1309 * IDs by this user to retrieve
1311 * @return array A list of all of the given user's notes, or an empty list
1312 * if the viewer lacks permissions or if there are no visible
1315 public function ¬es_get($uid, $note_ids = null) {
1316 return $this->call_method('notes.get',
1317 array('uid' => $uid,
1318 'note_ids' => $note_ids));
1323 * Returns the outstanding notifications for the session user.
1325 * @return array An assoc array of notification count objects for
1326 * 'messages', 'pokes' and 'shares', a uid list of
1327 * 'friend_requests', a gid list of 'group_invites',
1328 * and an eid list of 'event_invites'
1330 public function ¬ifications_get() {
1331 return $this->call_method('facebook.notifications.get');
1335 * Sends a notification to the specified users.
1337 * @return A comma separated list of successful recipients
1339 * API_EC_PARAM_USER_ID_LIST
1341 public function ¬ifications_send($to_ids, $notification, $type) {
1342 return $this->call_method('facebook.notifications.send',
1343 array('to_ids' => $to_ids,
1344 'notification' => $notification,
1349 * Sends an email to the specified user of the application.
1351 * @param array/string $recipients array of ids of the recipients (csv is deprecated)
1352 * @param string $subject subject of the email
1353 * @param string $text (plain text) body of the email
1354 * @param string $fbml fbml markup for an html version of the email
1356 * @return string A comma separated list of successful recipients
1358 * API_EC_PARAM_USER_ID_LIST
1360 public function ¬ifications_sendEmail($recipients,
1364 return $this->call_method('facebook.notifications.sendEmail',
1365 array('recipients' => $recipients,
1366 'subject' => $subject,
1372 * Returns the requested info fields for the requested set of pages.
1374 * @param array/string $page_ids an array of page ids (csv is deprecated)
1375 * @param array/string $fields an array of strings describing the
1376 * info fields desired (csv is deprecated)
1377 * @param int $uid (Optional) limit results to pages of which this
1379 * @param string type limits results to a particular type of page.
1381 * @return array An array of pages
1383 public function &pages_getInfo($page_ids, $fields, $uid, $type) {
1384 return $this->call_method('facebook.pages.getInfo',
1385 array('page_ids' => $page_ids,
1386 'fields' => $fields,
1392 * Returns true if the given user is an admin for the passed page.
1394 * @param int $page_id target page id
1395 * @param int $uid (Optional) user id (defaults to the logged-in user)
1397 * @return bool true on success
1399 public function &pages_isAdmin($page_id, $uid = null) {
1400 return $this->call_method('facebook.pages.isAdmin',
1401 array('page_id' => $page_id,
1406 * Returns whether or not the given page has added the application.
1408 * @param int $page_id target page id
1410 * @return bool true on success
1412 public function &pages_isAppAdded($page_id) {
1413 return $this->call_method('facebook.pages.isAppAdded',
1414 array('page_id' => $page_id));
1418 * Returns true if logged in user is a fan for the passed page.
1420 * @param int $page_id target page id
1421 * @param int $uid user to compare. If empty, the logged in user.
1423 * @return bool true on success
1425 public function &pages_isFan($page_id, $uid = null) {
1426 return $this->call_method('facebook.pages.isFan',
1427 array('page_id' => $page_id,
1432 * Adds a tag with the given information to a photo. See the wiki for details:
1434 * http://wiki.developers.facebook.com/index.php/Photos.addTag
1436 * @param int $pid The ID of the photo to be tagged
1437 * @param int $tag_uid The ID of the user being tagged. You must specify
1438 * either the $tag_uid or the $tag_text parameter
1439 * (unless $tags is specified).
1440 * @param string $tag_text Some text identifying the person being tagged.
1441 * You must specify either the $tag_uid or $tag_text
1442 * parameter (unless $tags is specified).
1443 * @param float $x The horizontal position of the tag, as a
1444 * percentage from 0 to 100, from the left of the
1446 * @param float $y The vertical position of the tag, as a percentage
1447 * from 0 to 100, from the top of the photo.
1448 * @param array $tags (Optional) An array of maps, where each map
1449 * can contain the tag_uid, tag_text, x, and y
1450 * parameters defined above. If specified, the
1451 * individual arguments are ignored.
1452 * @param int $owner_uid (Optional) The user ID of the user whose photo
1453 * you are tagging. If this parameter is not
1454 * specified, then it defaults to the session user.
1456 * @return bool true on success
1458 public function &photos_addTag($pid,
1465 return $this->call_method('facebook.photos.addTag',
1466 array('pid' => $pid,
1467 'tag_uid' => $tag_uid,
1468 'tag_text' => $tag_text,
1471 'tags' => (is_array($tags)) ? json_encode($tags) : null,
1472 'owner_uid' => $this->get_uid($owner_uid)));
1476 * Creates and returns a new album owned by the specified user or the current
1479 * @param string $name The name of the album.
1480 * @param string $description (Optional) A description of the album.
1481 * @param string $location (Optional) A description of the location.
1482 * @param string $visible (Optional) A privacy setting for the album.
1483 * One of 'friends', 'friends-of-friends',
1484 * 'networks', or 'everyone'. Default 'everyone'.
1485 * @param int $uid (Optional) User id for creating the album; if
1486 * not specified, the session user is used.
1488 * @return array An album object
1490 public function &photos_createAlbum($name,
1495 return $this->call_method('facebook.photos.createAlbum',
1496 array('name' => $name,
1497 'description' => $description,
1498 'location' => $location,
1499 'visible' => $visible,
1500 'uid' => $this->get_uid($uid)));
1504 * Returns photos according to the filters specified.
1506 * @param int $subj_id (Optional) Filter by uid of user tagged in the photos.
1507 * @param int $aid (Optional) Filter by an album, as returned by
1509 * @param array/string $pids (Optional) Restrict to an array of pids
1510 * (csv is deprecated)
1512 * Note that at least one of these parameters needs to be specified, or an
1513 * error is returned.
1515 * @return array An array of photo objects.
1517 public function &photos_get($subj_id, $aid, $pids) {
1518 return $this->call_method('facebook.photos.get',
1519 array('subj_id' => $subj_id, 'aid' => $aid, 'pids' => $pids));
1523 * Returns the albums created by the given user.
1525 * @param int $uid (Optional) The uid of the user whose albums you want.
1526 * A null will return the albums of the session user.
1527 * @param string $aids (Optional) An array of aids to restrict
1528 * the query. (csv is deprecated)
1530 * Note that at least one of the (uid, aids) parameters must be specified.
1532 * @returns an array of album objects.
1534 public function &photos_getAlbums($uid, $aids) {
1535 return $this->call_method('facebook.photos.getAlbums',
1536 array('uid' => $uid,
1541 * Returns the tags on all photos specified.
1543 * @param string $pids A list of pids to query
1545 * @return array An array of photo tag objects, which include pid,
1546 * subject uid, and two floating-point numbers (xcoord, ycoord)
1547 * for tag pixel location.
1549 public function &photos_getTags($pids) {
1550 return $this->call_method('facebook.photos.getTags',
1551 array('pids' => $pids));
1557 * @param string $file The location of the photo on the local filesystem.
1558 * @param int $aid (Optional) The album into which to upload the
1560 * @param string $caption (Optional) A caption for the photo.
1561 * @param int uid (Optional) The user ID of the user whose photo you
1564 * @return array An array of user objects
1566 public function photos_upload($file, $aid=null, $caption=null, $uid=null) {
1567 return $this->call_upload_method('facebook.photos.upload',
1568 array('aid' => $aid,
1569 'caption' => $caption,
1578 * @param string $file The location of the video on the local filesystem.
1579 * @param string $title (Optional) A title for the video. Titles over 65 characters in length will be truncated.
1580 * @param string $description (Optional) A description for the video.
1582 * @return array An array with the video's ID, title, description, and a link to view it on Facebook.
1584 public function video_upload($file, $title=null, $description=null) {
1585 return $this->call_upload_method('facebook.video.upload',
1586 array('title' => $title,
1587 'description' => $description),
1589 Facebook::get_facebook_url('api-video') . '/restserver.php');
1593 * Returns an array with the video limitations imposed on the current session's
1594 * associated user. Maximum length is measured in seconds; maximum size is
1595 * measured in bytes.
1597 * @return array Array with "length" and "size" keys
1599 public function &video_getUploadLimits() {
1600 return $this->call_method('facebook.video.getUploadLimits');
1604 * Returns the requested info fields for the requested set of users.
1606 * @param array/string $uids An array of user ids (csv is deprecated)
1607 * @param array/string $fields An array of info field names desired (csv is deprecated)
1609 * @return array An array of user objects
1611 public function &users_getInfo($uids, $fields) {
1612 return $this->call_method('facebook.users.getInfo',
1613 array('uids' => $uids,
1614 'fields' => $fields));
1618 * Returns the requested info fields for the requested set of users. A
1619 * session key must not be specified. Only data about users that have
1620 * authorized your application will be returned.
1622 * Check the wiki for fields that can be queried through this API call.
1623 * Data returned from here should not be used for rendering to application
1624 * users, use users.getInfo instead, so that proper privacy rules will be
1627 * @param array/string $uids An array of user ids (csv is deprecated)
1628 * @param array/string $fields An array of info field names desired (csv is deprecated)
1630 * @return array An array of user objects
1632 public function &users_getStandardInfo($uids, $fields) {
1633 return $this->call_method('facebook.users.getStandardInfo',
1634 array('uids' => $uids,
1635 'fields' => $fields));
1639 * Returns the user corresponding to the current session object.
1641 * @return integer User id
1643 public function &users_getLoggedInUser() {
1644 return $this->call_method('facebook.users.getLoggedInUser');
1648 * Returns 1 if the user has the specified permission, 0 otherwise.
1649 * http://wiki.developers.facebook.com/index.php/Users.hasAppPermission
1651 * @return integer 1 or 0
1653 public function &users_hasAppPermission($ext_perm, $uid=null) {
1654 return $this->call_method('facebook.users.hasAppPermission',
1655 array('ext_perm' => $ext_perm, 'uid' => $uid));
1659 * Returns whether or not the user corresponding to the current
1660 * session object has the give the app basic authorization.
1662 * @return boolean true if the user has authorized the app
1664 public function &users_isAppUser($uid=null) {
1665 if ($uid === null && isset($this->is_user)) {
1666 return $this->is_user;
1669 return $this->call_method('facebook.users.isAppUser', array('uid' => $uid));
1673 * Returns whether or not the user corresponding to the current
1674 * session object is verified by Facebook. See the documentation
1675 * for Users.isVerified for details.
1677 * @return boolean true if the user is verified
1679 public function &users_isVerified() {
1680 return $this->call_method('facebook.users.isVerified');
1684 * Sets the users' current status message. Message does NOT contain the
1685 * word "is" , so make sure to include a verb.
1687 * Example: setStatus("is loving the API!")
1688 * will produce the status "Luke is loving the API!"
1690 * @param string $status text-only message to set
1691 * @param int $uid user to set for (defaults to the
1693 * @param bool $clear whether or not to clear the status,
1694 * instead of setting it
1695 * @param bool $status_includes_verb if true, the word "is" will *not* be
1696 * prepended to the status message
1700 public function &users_setStatus($status,
1703 $status_includes_verb = true) {
1705 'status' => $status,
1708 'status_includes_verb' => $status_includes_verb,
1710 return $this->call_method('facebook.users.setStatus', $args);
1714 * Gets the comments for a particular xid. This is essentially a wrapper
1715 * around the comment FQL table.
1717 * @param string $xid external id associated with the comments
1719 * @return array of comment objects
1721 public function &comments_get($xid) {
1722 $args = array('xid' => $xid);
1723 return $this->call_method('facebook.comments.get', $args);
1727 * Add a comment to a particular xid on behalf of a user. If called
1728 * without an app_secret (with session secret), this will only work
1729 * for the session user.
1731 * @param string $xid external id associated with the comments
1732 * @param string $text text of the comment
1733 * @param int $uid user adding the comment (def: session user)
1734 * @param string $title optional title for the stream story
1735 * @param string $url optional url for the stream story
1736 * @param bool $publish_to_stream publish a feed story about this comment?
1737 * a link will be generated to title/url in the story
1739 * @return string comment_id associated with the comment
1741 public function &comments_add($xid, $text, $uid=0, $title='', $url='',
1742 $publish_to_stream=false) {
1745 'uid' => $this->get_uid($uid),
1749 'publish_to_stream' => $publish_to_stream);
1751 return $this->call_method('facebook.comments.add', $args);
1755 * Remove a particular comment.
1757 * @param string $xid the external id associated with the comments
1758 * @param string $comment_id id of the comment to remove (returned by
1759 * comments.add and comments.get)
1763 public function &comments_remove($xid, $comment_id) {
1766 'comment_id' => $comment_id);
1767 return $this->call_method('facebook.comments.remove', $args);
1771 * Gets the stream on behalf of a user using a set of users. This
1772 * call will return the latest $limit queries between $start_time
1775 * @param int $viewer_id user making the call (def: session)
1776 * @param array $source_ids users/pages to look at (def: all connections)
1777 * @param int $start_time start time to look for stories (def: 1 day ago)
1778 * @param int $end_time end time to look for stories (def: now)
1779 * @param int $limit number of stories to attempt to fetch (def: 30)
1780 * @param string $filter_key key returned by stream.getFilters to fetch
1781 * @param array $metadata metadata to include with the return, allows
1782 * requested metadata to be returned, such as
1783 * profiles, albums, photo_tags
1786 * 'posts' => array of posts,
1787 * // if requested, the following data may be returned
1788 * 'profiles' => array of profile metadata of users/pages in posts
1789 * 'albums' => array of album metadata in posts
1790 * 'photo_tags' => array of photo_tags for photos in posts
1793 public function &stream_get($viewer_id = null,
1800 'viewer_id' => $viewer_id,
1801 'source_ids' => $source_ids,
1802 'start_time' => $start_time,
1803 'end_time' => $end_time,
1805 'filter_key' => $filter_key);
1806 return $this->call_method('facebook.stream.get', $args);
1810 * Gets the filters (with relevant filter keys for stream.get) for a
1811 * particular user. These filters are typical things like news feed,
1812 * friend lists, networks. They can be used to filter the stream
1813 * without complex queries to determine which ids belong in which groups.
1815 * @param int $uid user to get filters for
1817 * @return array of stream filter objects
1819 public function &stream_getFilters($uid = null) {
1820 $args = array('uid' => $uid);
1821 return $this->call_method('facebook.stream.getFilters', $args);
1825 * Gets the full comments given a post_id from stream.get or the
1826 * stream FQL table. Initially, only a set of preview comments are
1827 * returned because some posts can have many comments.
1829 * @param string $post_id id of the post to get comments for
1831 * @return array of comment objects
1833 public function &stream_getComments($post_id) {
1834 $args = array('post_id' => $post_id);
1835 return $this->call_method('facebook.stream.getComments', $args);
1839 * Sets the FBML for the profile of the user attached to this session.
1841 * @param string $markup The FBML that describes the profile
1842 * presence of this app for the user
1843 * @param int $uid The user
1844 * @param string $profile Profile FBML
1845 * @param string $profile_action Profile action FBML (deprecated)
1846 * @param string $mobile_profile Mobile profile FBML
1847 * @param string $profile_main Main Tab profile FBML
1849 * @return array A list of strings describing any compile errors for the
1852 function profile_setFBML($markup,
1858 return $this->call_method('facebook.profile.setFBML',
1859 array('markup' => $markup,
1861 'profile' => $profile,
1862 'profile_action' => $profile_action,
1863 'mobile_profile' => $mobile_profile,
1864 'profile_main' => $profile_main));
1868 * Gets the FBML for the profile box that is currently set for a user's
1869 * profile (your application set the FBML previously by calling the
1870 * profile.setFBML method).
1872 * @param int $uid (Optional) User id to lookup; defaults to session.
1873 * @param int $type (Optional) 1 for original style, 2 for profile_main boxes
1875 * @return string The FBML
1877 public function &profile_getFBML($uid=null, $type=null) {
1878 return $this->call_method('facebook.profile.getFBML',
1879 array('uid' => $uid,
1884 * Returns the specified user's application info section for the calling
1885 * application. These info sections have either been set via a previous
1886 * profile.setInfo call or by the user editing them directly.
1888 * @param int $uid (Optional) User id to lookup; defaults to session.
1890 * @return array Info fields for the current user. See wiki for structure:
1892 * http://wiki.developers.facebook.com/index.php/Profile.getInfo
1895 public function &profile_getInfo($uid=null) {
1896 return $this->call_method('facebook.profile.getInfo',
1897 array('uid' => $uid));
1901 * Returns the options associated with the specified info field for an
1902 * application info section.
1904 * @param string $field The title of the field
1906 * @return array An array of info options.
1908 public function &profile_getInfoOptions($field) {
1909 return $this->call_method('facebook.profile.getInfoOptions',
1910 array('field' => $field));
1914 * Configures an application info section that the specified user can install
1915 * on the Info tab of her profile. For details on the structure of an info
1916 * field, please see:
1918 * http://wiki.developers.facebook.com/index.php/Profile.setInfo
1920 * @param string $title Title / header of the info section
1921 * @param int $type 1 for text-only, 5 for thumbnail views
1922 * @param array $info_fields An array of info fields. See wiki for details.
1923 * @param int $uid (Optional)
1925 * @return bool true on success
1927 public function &profile_setInfo($title, $type, $info_fields, $uid=null) {
1928 return $this->call_method('facebook.profile.setInfo',
1929 array('uid' => $uid,
1932 'info_fields' => json_encode($info_fields)));
1936 * Specifies the objects for a field for an application info section. These
1937 * options populate the typeahead for a thumbnail.
1939 * @param string $field The title of the field
1940 * @param array $options An array of items for a thumbnail, including
1941 * 'label', 'link', and optionally 'image',
1942 * 'description' and 'sublabel'
1944 * @return bool true on success
1946 public function profile_setInfoOptions($field, $options) {
1947 return $this->call_method('facebook.profile.setInfoOptions',
1948 array('field' => $field,
1949 'options' => json_encode($options)));
1953 * Get all the marketplace categories.
1955 * @return array A list of category names
1957 function marketplace_getCategories() {
1958 return $this->call_method('facebook.marketplace.getCategories',
1963 * Get all the marketplace subcategories for a particular category.
1965 * @param category The category for which we are pulling subcategories
1967 * @return array A list of subcategory names
1969 function marketplace_getSubCategories($category) {
1970 return $this->call_method('facebook.marketplace.getSubCategories',
1971 array('category' => $category));
1975 * Get listings by either listing_id or user.
1977 * @param listing_ids An array of listing_ids (optional)
1978 * @param uids An array of user ids (optional)
1980 * @return array The data for matched listings
1982 function marketplace_getListings($listing_ids, $uids) {
1983 return $this->call_method('facebook.marketplace.getListings',
1984 array('listing_ids' => $listing_ids, 'uids' => $uids));
1988 * Search for Marketplace listings. All arguments are optional, though at
1989 * least one must be filled out to retrieve results.
1991 * @param category The category in which to search (optional)
1992 * @param subcategory The subcategory in which to search (optional)
1993 * @param query A query string (optional)
1995 * @return array The data for matched listings
1997 function marketplace_search($category, $subcategory, $query) {
1998 return $this->call_method('facebook.marketplace.search',
1999 array('category' => $category,
2000 'subcategory' => $subcategory,
2001 'query' => $query));
2005 * Remove a listing from Marketplace.
2007 * @param listing_id The id of the listing to be removed
2008 * @param status 'SUCCESS', 'NOT_SUCCESS', or 'DEFAULT'
2010 * @return bool True on success
2012 function marketplace_removeListing($listing_id,
2015 return $this->call_method('facebook.marketplace.removeListing',
2016 array('listing_id' => $listing_id,
2017 'status' => $status,
2022 * Create/modify a Marketplace listing for the loggedinuser.
2024 * @param int listing_id The id of a listing to be modified, 0
2025 * for a new listing.
2026 * @param show_on_profile bool Should we show this listing on the
2028 * @param listing_attrs array An array of the listing data
2030 * @return int The listing_id (unchanged if modifying an existing listing).
2032 function marketplace_createListing($listing_id,
2036 return $this->call_method('facebook.marketplace.createListing',
2037 array('listing_id' => $listing_id,
2038 'show_on_profile' => $show_on_profile,
2039 'listing_attrs' => json_encode($attrs),
2043 /////////////////////////////////////////////////////////////////////////////
2047 * Set a user preference.
2049 * @param pref_id preference identifier (0-200)
2050 * @param value preferece's value
2051 * @param uid the user id (defaults to current session user)
2053 * API_EC_DATA_DATABASE_ERROR
2055 * API_EC_DATA_QUOTA_EXCEEDED
2056 * API_EC_DATA_UNKNOWN_ERROR
2057 * API_EC_PERMISSION_OTHER_USER
2059 public function &data_setUserPreference($pref_id, $value, $uid = null) {
2060 return $this->call_method('facebook.data.setUserPreference',
2061 array('pref_id' => $pref_id,
2063 'uid' => $this->get_uid($uid)));
2067 * Set a user's all preferences for this application.
2069 * @param values preferece values in an associative arrays
2070 * @param replace whether to replace all existing preferences or
2072 * @param uid the user id (defaults to current session user)
2074 * API_EC_DATA_DATABASE_ERROR
2076 * API_EC_DATA_QUOTA_EXCEEDED
2077 * API_EC_DATA_UNKNOWN_ERROR
2078 * API_EC_PERMISSION_OTHER_USER
2080 public function &data_setUserPreferences($values,
2083 return $this->call_method('facebook.data.setUserPreferences',
2084 array('values' => json_encode($values),
2085 'replace' => $replace,
2086 'uid' => $this->get_uid($uid)));
2090 * Get a user preference.
2092 * @param pref_id preference identifier (0-200)
2093 * @param uid the user id (defaults to current session user)
2094 * @return preference's value
2096 * API_EC_DATA_DATABASE_ERROR
2098 * API_EC_DATA_QUOTA_EXCEEDED
2099 * API_EC_DATA_UNKNOWN_ERROR
2100 * API_EC_PERMISSION_OTHER_USER
2102 public function &data_getUserPreference($pref_id, $uid = null) {
2103 return $this->call_method('facebook.data.getUserPreference',
2104 array('pref_id' => $pref_id,
2105 'uid' => $this->get_uid($uid)));
2109 * Get a user preference.
2111 * @param uid the user id (defaults to current session user)
2112 * @return preference values
2114 * API_EC_DATA_DATABASE_ERROR
2115 * API_EC_DATA_QUOTA_EXCEEDED
2116 * API_EC_DATA_UNKNOWN_ERROR
2117 * API_EC_PERMISSION_OTHER_USER
2119 public function &data_getUserPreferences($uid = null) {
2120 return $this->call_method('facebook.data.getUserPreferences',
2121 array('uid' => $this->get_uid($uid)));
2125 * Create a new object type.
2127 * @param name object type's name
2129 * API_EC_DATA_DATABASE_ERROR
2130 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2133 * API_EC_DATA_INVALID_OPERATION
2134 * API_EC_DATA_QUOTA_EXCEEDED
2135 * API_EC_DATA_UNKNOWN_ERROR
2137 public function &data_createObjectType($name) {
2138 return $this->call_method('facebook.data.createObjectType',
2139 array('name' => $name));
2143 * Delete an object type.
2145 * @param obj_type object type's name
2147 * API_EC_DATA_DATABASE_ERROR
2148 * API_EC_DATA_OBJECT_NOT_FOUND
2151 * API_EC_DATA_INVALID_OPERATION
2152 * API_EC_DATA_QUOTA_EXCEEDED
2153 * API_EC_DATA_UNKNOWN_ERROR
2155 public function &data_dropObjectType($obj_type) {
2156 return $this->call_method('facebook.data.dropObjectType',
2157 array('obj_type' => $obj_type));
2161 * Rename an object type.
2163 * @param obj_type object type's name
2164 * @param new_name new object type's name
2166 * API_EC_DATA_DATABASE_ERROR
2167 * API_EC_DATA_OBJECT_NOT_FOUND
2168 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2171 * API_EC_DATA_INVALID_OPERATION
2172 * API_EC_DATA_QUOTA_EXCEEDED
2173 * API_EC_DATA_UNKNOWN_ERROR
2175 public function &data_renameObjectType($obj_type, $new_name) {
2176 return $this->call_method('facebook.data.renameObjectType',
2177 array('obj_type' => $obj_type,
2178 'new_name' => $new_name));
2182 * Add a new property to an object type.
2184 * @param obj_type object type's name
2185 * @param prop_name name of the property to add
2186 * @param prop_type 1: integer; 2: string; 3: text blob
2188 * API_EC_DATA_DATABASE_ERROR
2189 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2192 * API_EC_DATA_INVALID_OPERATION
2193 * API_EC_DATA_QUOTA_EXCEEDED
2194 * API_EC_DATA_UNKNOWN_ERROR
2196 public function &data_defineObjectProperty($obj_type,
2199 return $this->call_method('facebook.data.defineObjectProperty',
2200 array('obj_type' => $obj_type,
2201 'prop_name' => $prop_name,
2202 'prop_type' => $prop_type));
2206 * Remove a previously defined property from an object type.
2208 * @param obj_type object type's name
2209 * @param prop_name name of the property to remove
2211 * API_EC_DATA_DATABASE_ERROR
2212 * API_EC_DATA_OBJECT_NOT_FOUND
2215 * API_EC_DATA_INVALID_OPERATION
2216 * API_EC_DATA_QUOTA_EXCEEDED
2217 * API_EC_DATA_UNKNOWN_ERROR
2219 public function &data_undefineObjectProperty($obj_type, $prop_name) {
2220 return $this->call_method('facebook.data.undefineObjectProperty',
2221 array('obj_type' => $obj_type,
2222 'prop_name' => $prop_name));
2226 * Rename a previously defined property of an object type.
2228 * @param obj_type object type's name
2229 * @param prop_name name of the property to rename
2230 * @param new_name new name to use
2232 * API_EC_DATA_DATABASE_ERROR
2233 * API_EC_DATA_OBJECT_NOT_FOUND
2234 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2237 * API_EC_DATA_INVALID_OPERATION
2238 * API_EC_DATA_QUOTA_EXCEEDED
2239 * API_EC_DATA_UNKNOWN_ERROR
2241 public function &data_renameObjectProperty($obj_type, $prop_name,
2243 return $this->call_method('facebook.data.renameObjectProperty',
2244 array('obj_type' => $obj_type,
2245 'prop_name' => $prop_name,
2246 'new_name' => $new_name));
2250 * Retrieve a list of all object types that have defined for the application.
2252 * @return a list of object type names
2254 * API_EC_DATA_DATABASE_ERROR
2256 * API_EC_DATA_QUOTA_EXCEEDED
2257 * API_EC_DATA_UNKNOWN_ERROR
2259 public function &data_getObjectTypes() {
2260 return $this->call_method('facebook.data.getObjectTypes');
2264 * Get definitions of all properties of an object type.
2266 * @param obj_type object type's name
2267 * @return pairs of property name and property types
2269 * API_EC_DATA_DATABASE_ERROR
2272 * API_EC_DATA_OBJECT_NOT_FOUND
2273 * API_EC_DATA_QUOTA_EXCEEDED
2274 * API_EC_DATA_UNKNOWN_ERROR
2276 public function &data_getObjectType($obj_type) {
2277 return $this->call_method('facebook.data.getObjectType',
2278 array('obj_type' => $obj_type));
2282 * Create a new object.
2284 * @param obj_type object type's name
2285 * @param properties (optional) properties to set initially
2286 * @return newly created object's id
2288 * API_EC_DATA_DATABASE_ERROR
2291 * API_EC_DATA_INVALID_OPERATION
2292 * API_EC_DATA_QUOTA_EXCEEDED
2293 * API_EC_DATA_UNKNOWN_ERROR
2295 public function &data_createObject($obj_type, $properties = null) {
2296 return $this->call_method('facebook.data.createObject',
2297 array('obj_type' => $obj_type,
2298 'properties' => json_encode($properties)));
2302 * Update an existing object.
2304 * @param obj_id object's id
2305 * @param properties new properties
2306 * @param replace true for replacing existing properties;
2309 * API_EC_DATA_DATABASE_ERROR
2310 * API_EC_DATA_OBJECT_NOT_FOUND
2313 * API_EC_DATA_INVALID_OPERATION
2314 * API_EC_DATA_QUOTA_EXCEEDED
2315 * API_EC_DATA_UNKNOWN_ERROR
2317 public function &data_updateObject($obj_id, $properties, $replace = false) {
2318 return $this->call_method('facebook.data.updateObject',
2319 array('obj_id' => $obj_id,
2320 'properties' => json_encode($properties),
2321 'replace' => $replace));
2325 * Delete an existing object.
2327 * @param obj_id object's id
2329 * API_EC_DATA_DATABASE_ERROR
2330 * API_EC_DATA_OBJECT_NOT_FOUND
2333 * API_EC_DATA_INVALID_OPERATION
2334 * API_EC_DATA_QUOTA_EXCEEDED
2335 * API_EC_DATA_UNKNOWN_ERROR
2337 public function &data_deleteObject($obj_id) {
2338 return $this->call_method('facebook.data.deleteObject',
2339 array('obj_id' => $obj_id));
2343 * Delete a list of objects.
2345 * @param obj_ids objects to delete
2347 * API_EC_DATA_DATABASE_ERROR
2350 * API_EC_DATA_INVALID_OPERATION
2351 * API_EC_DATA_QUOTA_EXCEEDED
2352 * API_EC_DATA_UNKNOWN_ERROR
2354 public function &data_deleteObjects($obj_ids) {
2355 return $this->call_method('facebook.data.deleteObjects',
2356 array('obj_ids' => json_encode($obj_ids)));
2360 * Get a single property value of an object.
2362 * @param obj_id object's id
2363 * @param prop_name individual property's name
2364 * @return individual property's value
2366 * API_EC_DATA_DATABASE_ERROR
2367 * API_EC_DATA_OBJECT_NOT_FOUND
2370 * API_EC_DATA_INVALID_OPERATION
2371 * API_EC_DATA_QUOTA_EXCEEDED
2372 * API_EC_DATA_UNKNOWN_ERROR
2374 public function &data_getObjectProperty($obj_id, $prop_name) {
2375 return $this->call_method('facebook.data.getObjectProperty',
2376 array('obj_id' => $obj_id,
2377 'prop_name' => $prop_name));
2381 * Get properties of an object.
2383 * @param obj_id object's id
2384 * @param prop_names (optional) properties to return; null for all.
2385 * @return specified properties of an object
2387 * API_EC_DATA_DATABASE_ERROR
2388 * API_EC_DATA_OBJECT_NOT_FOUND
2391 * API_EC_DATA_INVALID_OPERATION
2392 * API_EC_DATA_QUOTA_EXCEEDED
2393 * API_EC_DATA_UNKNOWN_ERROR
2395 public function &data_getObject($obj_id, $prop_names = null) {
2396 return $this->call_method('facebook.data.getObject',
2397 array('obj_id' => $obj_id,
2398 'prop_names' => json_encode($prop_names)));
2402 * Get properties of a list of objects.
2404 * @param obj_ids object ids
2405 * @param prop_names (optional) properties to return; null for all.
2406 * @return specified properties of an object
2408 * API_EC_DATA_DATABASE_ERROR
2409 * API_EC_DATA_OBJECT_NOT_FOUND
2412 * API_EC_DATA_INVALID_OPERATION
2413 * API_EC_DATA_QUOTA_EXCEEDED
2414 * API_EC_DATA_UNKNOWN_ERROR
2416 public function &data_getObjects($obj_ids, $prop_names = null) {
2417 return $this->call_method('facebook.data.getObjects',
2418 array('obj_ids' => json_encode($obj_ids),
2419 'prop_names' => json_encode($prop_names)));
2423 * Set a single property value of an object.
2425 * @param obj_id object's id
2426 * @param prop_name individual property's name
2427 * @param prop_value new value to set
2429 * API_EC_DATA_DATABASE_ERROR
2430 * API_EC_DATA_OBJECT_NOT_FOUND
2433 * API_EC_DATA_INVALID_OPERATION
2434 * API_EC_DATA_QUOTA_EXCEEDED
2435 * API_EC_DATA_UNKNOWN_ERROR
2437 public function &data_setObjectProperty($obj_id, $prop_name,
2439 return $this->call_method('facebook.data.setObjectProperty',
2440 array('obj_id' => $obj_id,
2441 'prop_name' => $prop_name,
2442 'prop_value' => $prop_value));
2446 * Read hash value by key.
2448 * @param obj_type object type's name
2449 * @param key hash key
2450 * @param prop_name (optional) individual property's name
2451 * @return hash value
2453 * API_EC_DATA_DATABASE_ERROR
2456 * API_EC_DATA_INVALID_OPERATION
2457 * API_EC_DATA_QUOTA_EXCEEDED
2458 * API_EC_DATA_UNKNOWN_ERROR
2460 public function &data_getHashValue($obj_type, $key, $prop_name = null) {
2461 return $this->call_method('facebook.data.getHashValue',
2462 array('obj_type' => $obj_type,
2464 'prop_name' => $prop_name));
2468 * Write hash value by key.
2470 * @param obj_type object type's name
2471 * @param key hash key
2472 * @param value hash value
2473 * @param prop_name (optional) individual property's name
2475 * API_EC_DATA_DATABASE_ERROR
2478 * API_EC_DATA_INVALID_OPERATION
2479 * API_EC_DATA_QUOTA_EXCEEDED
2480 * API_EC_DATA_UNKNOWN_ERROR
2482 public function &data_setHashValue($obj_type,
2485 $prop_name = null) {
2486 return $this->call_method('facebook.data.setHashValue',
2487 array('obj_type' => $obj_type,
2490 'prop_name' => $prop_name));
2494 * Increase a hash value by specified increment atomically.
2496 * @param obj_type object type's name
2497 * @param key hash key
2498 * @param prop_name individual property's name
2499 * @param increment (optional) default is 1
2500 * @return incremented hash value
2502 * API_EC_DATA_DATABASE_ERROR
2505 * API_EC_DATA_INVALID_OPERATION
2506 * API_EC_DATA_QUOTA_EXCEEDED
2507 * API_EC_DATA_UNKNOWN_ERROR
2509 public function &data_incHashValue($obj_type,
2513 return $this->call_method('facebook.data.incHashValue',
2514 array('obj_type' => $obj_type,
2516 'prop_name' => $prop_name,
2517 'increment' => $increment));
2521 * Remove a hash key and its values.
2523 * @param obj_type object type's name
2524 * @param key hash key
2526 * API_EC_DATA_DATABASE_ERROR
2529 * API_EC_DATA_INVALID_OPERATION
2530 * API_EC_DATA_QUOTA_EXCEEDED
2531 * API_EC_DATA_UNKNOWN_ERROR
2533 public function &data_removeHashKey($obj_type, $key) {
2534 return $this->call_method('facebook.data.removeHashKey',
2535 array('obj_type' => $obj_type,
2540 * Remove hash keys and their values.
2542 * @param obj_type object type's name
2543 * @param keys hash keys
2545 * API_EC_DATA_DATABASE_ERROR
2548 * API_EC_DATA_INVALID_OPERATION
2549 * API_EC_DATA_QUOTA_EXCEEDED
2550 * API_EC_DATA_UNKNOWN_ERROR
2552 public function &data_removeHashKeys($obj_type, $keys) {
2553 return $this->call_method('facebook.data.removeHashKeys',
2554 array('obj_type' => $obj_type,
2555 'keys' => json_encode($keys)));
2559 * Define an object association.
2561 * @param name name of this association
2562 * @param assoc_type 1: one-way 2: two-way symmetric 3: two-way asymmetric
2563 * @param assoc_info1 needed info about first object type
2564 * @param assoc_info2 needed info about second object type
2565 * @param inverse (optional) name of reverse association
2567 * API_EC_DATA_DATABASE_ERROR
2568 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2571 * API_EC_DATA_INVALID_OPERATION
2572 * API_EC_DATA_QUOTA_EXCEEDED
2573 * API_EC_DATA_UNKNOWN_ERROR
2575 public function &data_defineAssociation($name, $assoc_type, $assoc_info1,
2576 $assoc_info2, $inverse = null) {
2577 return $this->call_method('facebook.data.defineAssociation',
2578 array('name' => $name,
2579 'assoc_type' => $assoc_type,
2580 'assoc_info1' => json_encode($assoc_info1),
2581 'assoc_info2' => json_encode($assoc_info2),
2582 'inverse' => $inverse));
2586 * Undefine an object association.
2588 * @param name name of this association
2590 * API_EC_DATA_DATABASE_ERROR
2591 * API_EC_DATA_OBJECT_NOT_FOUND
2594 * API_EC_DATA_INVALID_OPERATION
2595 * API_EC_DATA_QUOTA_EXCEEDED
2596 * API_EC_DATA_UNKNOWN_ERROR
2598 public function &data_undefineAssociation($name) {
2599 return $this->call_method('facebook.data.undefineAssociation',
2600 array('name' => $name));
2604 * Rename an object association or aliases.
2606 * @param name name of this association
2607 * @param new_name (optional) new name of this association
2608 * @param new_alias1 (optional) new alias for object type 1
2609 * @param new_alias2 (optional) new alias for object type 2
2611 * API_EC_DATA_DATABASE_ERROR
2612 * API_EC_DATA_OBJECT_ALREADY_EXISTS
2613 * API_EC_DATA_OBJECT_NOT_FOUND
2616 * API_EC_DATA_INVALID_OPERATION
2617 * API_EC_DATA_QUOTA_EXCEEDED
2618 * API_EC_DATA_UNKNOWN_ERROR
2620 public function &data_renameAssociation($name, $new_name, $new_alias1 = null,
2621 $new_alias2 = null) {
2622 return $this->call_method('facebook.data.renameAssociation',
2623 array('name' => $name,
2624 'new_name' => $new_name,
2625 'new_alias1' => $new_alias1,
2626 'new_alias2' => $new_alias2));
2630 * Get definition of an object association.
2632 * @param name name of this association
2633 * @return specified association
2635 * API_EC_DATA_DATABASE_ERROR
2636 * API_EC_DATA_OBJECT_NOT_FOUND
2639 * API_EC_DATA_QUOTA_EXCEEDED
2640 * API_EC_DATA_UNKNOWN_ERROR
2642 public function &data_getAssociationDefinition($name) {
2643 return $this->call_method('facebook.data.getAssociationDefinition',
2644 array('name' => $name));
2648 * Get definition of all associations.
2650 * @return all defined associations
2652 * API_EC_DATA_DATABASE_ERROR
2654 * API_EC_DATA_QUOTA_EXCEEDED
2655 * API_EC_DATA_UNKNOWN_ERROR
2657 public function &data_getAssociationDefinitions() {
2658 return $this->call_method('facebook.data.getAssociationDefinitions',
2663 * Create or modify an association between two objects.
2665 * @param name name of association
2666 * @param obj_id1 id of first object
2667 * @param obj_id2 id of second object
2668 * @param data (optional) extra string data to store
2669 * @param assoc_time (optional) extra time data; default to creation time
2671 * API_EC_DATA_DATABASE_ERROR
2674 * API_EC_DATA_INVALID_OPERATION
2675 * API_EC_DATA_QUOTA_EXCEEDED
2676 * API_EC_DATA_UNKNOWN_ERROR
2678 public function &data_setAssociation($name, $obj_id1, $obj_id2, $data = null,
2679 $assoc_time = null) {
2680 return $this->call_method('facebook.data.setAssociation',
2681 array('name' => $name,
2682 'obj_id1' => $obj_id1,
2683 'obj_id2' => $obj_id2,
2685 'assoc_time' => $assoc_time));
2689 * Create or modify associations between objects.
2691 * @param assocs associations to set
2692 * @param name (optional) name of association
2694 * API_EC_DATA_DATABASE_ERROR
2697 * API_EC_DATA_INVALID_OPERATION
2698 * API_EC_DATA_QUOTA_EXCEEDED
2699 * API_EC_DATA_UNKNOWN_ERROR
2701 public function &data_setAssociations($assocs, $name = null) {
2702 return $this->call_method('facebook.data.setAssociations',
2703 array('assocs' => json_encode($assocs),
2708 * Remove an association between two objects.
2710 * @param name name of association
2711 * @param obj_id1 id of first object
2712 * @param obj_id2 id of second object
2714 * API_EC_DATA_DATABASE_ERROR
2715 * API_EC_DATA_OBJECT_NOT_FOUND
2718 * API_EC_DATA_QUOTA_EXCEEDED
2719 * API_EC_DATA_UNKNOWN_ERROR
2721 public function &data_removeAssociation($name, $obj_id1, $obj_id2) {
2722 return $this->call_method('facebook.data.removeAssociation',
2723 array('name' => $name,
2724 'obj_id1' => $obj_id1,
2725 'obj_id2' => $obj_id2));
2729 * Remove associations between objects by specifying pairs of object ids.
2731 * @param assocs associations to remove
2732 * @param name (optional) name of association
2734 * API_EC_DATA_DATABASE_ERROR
2735 * API_EC_DATA_OBJECT_NOT_FOUND
2738 * API_EC_DATA_QUOTA_EXCEEDED
2739 * API_EC_DATA_UNKNOWN_ERROR
2741 public function &data_removeAssociations($assocs, $name = null) {
2742 return $this->call_method('facebook.data.removeAssociations',
2743 array('assocs' => json_encode($assocs),
2748 * Remove associations between objects by specifying one object id.
2750 * @param name name of association
2751 * @param obj_id who's association to remove
2753 * API_EC_DATA_DATABASE_ERROR
2754 * API_EC_DATA_OBJECT_NOT_FOUND
2757 * API_EC_DATA_INVALID_OPERATION
2758 * API_EC_DATA_QUOTA_EXCEEDED
2759 * API_EC_DATA_UNKNOWN_ERROR
2761 public function &data_removeAssociatedObjects($name, $obj_id) {
2762 return $this->call_method('facebook.data.removeAssociatedObjects',
2763 array('name' => $name,
2764 'obj_id' => $obj_id));
2768 * Retrieve a list of associated objects.
2770 * @param name name of association
2771 * @param obj_id who's association to retrieve
2772 * @param no_data only return object ids
2773 * @return associated objects
2775 * API_EC_DATA_DATABASE_ERROR
2776 * API_EC_DATA_OBJECT_NOT_FOUND
2779 * API_EC_DATA_INVALID_OPERATION
2780 * API_EC_DATA_QUOTA_EXCEEDED
2781 * API_EC_DATA_UNKNOWN_ERROR
2783 public function &data_getAssociatedObjects($name, $obj_id, $no_data = true) {
2784 return $this->call_method('facebook.data.getAssociatedObjects',
2785 array('name' => $name,
2786 'obj_id' => $obj_id,
2787 'no_data' => $no_data));
2791 * Count associated objects.
2793 * @param name name of association
2794 * @param obj_id who's association to retrieve
2795 * @return associated object's count
2797 * API_EC_DATA_DATABASE_ERROR
2798 * API_EC_DATA_OBJECT_NOT_FOUND
2801 * API_EC_DATA_INVALID_OPERATION
2802 * API_EC_DATA_QUOTA_EXCEEDED
2803 * API_EC_DATA_UNKNOWN_ERROR
2805 public function &data_getAssociatedObjectCount($name, $obj_id) {
2806 return $this->call_method('facebook.data.getAssociatedObjectCount',
2807 array('name' => $name,
2808 'obj_id' => $obj_id));
2812 * Get a list of associated object counts.
2814 * @param name name of association
2815 * @param obj_ids whose association to retrieve
2816 * @return associated object counts
2818 * API_EC_DATA_DATABASE_ERROR
2819 * API_EC_DATA_OBJECT_NOT_FOUND
2822 * API_EC_DATA_INVALID_OPERATION
2823 * API_EC_DATA_QUOTA_EXCEEDED
2824 * API_EC_DATA_UNKNOWN_ERROR
2826 public function &data_getAssociatedObjectCounts($name, $obj_ids) {
2827 return $this->call_method('facebook.data.getAssociatedObjectCounts',
2828 array('name' => $name,
2829 'obj_ids' => json_encode($obj_ids)));
2833 * Find all associations between two objects.
2835 * @param obj_id1 id of first object
2836 * @param obj_id2 id of second object
2837 * @param no_data only return association names without data
2838 * @return all associations between objects
2840 * API_EC_DATA_DATABASE_ERROR
2843 * API_EC_DATA_QUOTA_EXCEEDED
2844 * API_EC_DATA_UNKNOWN_ERROR
2846 public function &data_getAssociations($obj_id1, $obj_id2, $no_data = true) {
2847 return $this->call_method('facebook.data.getAssociations',
2848 array('obj_id1' => $obj_id1,
2849 'obj_id2' => $obj_id2,
2850 'no_data' => $no_data));
2854 * Get the properties that you have set for an app.
2856 * @param properties List of properties names to fetch
2858 * @return array A map from property name to value
2860 public function admin_getAppProperties($properties) {
2862 $this->call_method('facebook.admin.getAppProperties',
2863 array('properties' => json_encode($properties))), true);
2867 * Set properties for an app.
2869 * @param properties A map from property names to values
2871 * @return bool true on success
2873 public function admin_setAppProperties($properties) {
2874 return $this->call_method('facebook.admin.setAppProperties',
2875 array('properties' => json_encode($properties)));
2879 * Returns the allocation limit value for a specified integration point name
2880 * Integration point names are defined in lib/api/karma/constants.php in the
2883 * @param string $integration_point_name Name of an integration point
2884 * (see developer wiki for list).
2885 * @param int $uid Specific user to check the limit.
2887 * @return int Integration point allocation value
2889 public function &admin_getAllocation($integration_point_name, $uid=null) {
2890 return $this->call_method('facebook.admin.getAllocation',
2891 array('integration_point_name' => $integration_point_name,
2896 * Returns values for the specified metrics for the current application, in
2897 * the given time range. The metrics are collected for fixed-length periods,
2898 * and the times represent midnight at the end of each period.
2900 * @param start_time unix time for the start of the range
2901 * @param end_time unix time for the end of the range
2902 * @param period number of seconds in the desired period
2903 * @param metrics list of metrics to look up
2905 * @return array A map of the names and values for those metrics
2907 public function &admin_getMetrics($start_time, $end_time, $period, $metrics) {
2908 return $this->call_method('admin.getMetrics',
2909 array('start_time' => $start_time,
2910 'end_time' => $end_time,
2911 'period' => $period,
2912 'metrics' => json_encode($metrics)));
2916 * Sets application restriction info.
2918 * Applications can restrict themselves to only a limited user demographic
2919 * based on users' age and/or location or based on static predefined types
2920 * specified by facebook for specifying diff age restriction for diff
2923 * @param array $restriction_info The age restriction settings to set.
2925 * @return bool true on success
2927 public function admin_setRestrictionInfo($restriction_info = null) {
2928 $restriction_str = null;
2929 if (!empty($restriction_info)) {
2930 $restriction_str = json_encode($restriction_info);
2932 return $this->call_method('admin.setRestrictionInfo',
2933 array('restriction_str' => $restriction_str));
2937 * Gets application restriction info.
2939 * Applications can restrict themselves to only a limited user demographic
2940 * based on users' age and/or location or based on static predefined types
2941 * specified by facebook for specifying diff age restriction for diff
2944 * @return array The age restriction settings for this application.
2946 public function admin_getRestrictionInfo() {
2948 $this->call_method('admin.getRestrictionInfo'),
2954 * Bans a list of users from the app. Banned users can't
2955 * access the app's canvas page and forums.
2957 * @param array $uids an array of user ids
2958 * @return bool true on success
2960 public function admin_banUsers($uids) {
2961 return $this->call_method(
2962 'admin.banUsers', array('uids' => json_encode($uids)));
2966 * Unban users that have been previously banned with
2969 * @param array $uids an array of user ids
2970 * @return bool true on success
2972 public function admin_unbanUsers($uids) {
2973 return $this->call_method(
2974 'admin.unbanUsers', array('uids' => json_encode($uids)));
2978 * Gets the list of users that have been banned from the application.
2979 * $uids is an optional parameter that filters the result with the list
2980 * of provided user ids. If $uids is provided,
2981 * only banned user ids that are contained in $uids are returned.
2983 * @param array $uids an array of user ids to filter by
2984 * @return bool true on success
2987 public function admin_getBannedUsers($uids = null) {
2988 return $this->call_method(
2989 'admin.getBannedUsers',
2990 array('uids' => $uids ? json_encode($uids) : null));
2994 /* UTILITY FUNCTIONS */
2997 * Calls the specified normal POST method with the specified parameters.
2999 * @param string $method Name of the Facebook method to invoke
3000 * @param array $params A map of param names => param values
3002 * @return mixed Result of method call; this returns a reference to support
3003 * 'delayed returns' when in a batch context.
3004 * See: http://wiki.developers.facebook.com/index.php/Using_batching_API
3006 public function &call_method($method, $params = array()) {
3007 if ($this->format) {
3008 $params['format'] = $this->format;
3010 if (!$this->pending_batch()) {
3011 if ($this->call_as_apikey) {
3012 $params['call_as_apikey'] = $this->call_as_apikey;
3014 $data = $this->post_request($method, $params);
3015 $result = $this->convert_result($data, $method, $params);
3016 if (is_array($result) && isset($result['error_code'])) {
3017 throw new FacebookRestClientException($result['error_msg'],
3018 $result['error_code']);
3023 $batch_item = array('m' => $method, 'p' => $params, 'r' => & $result);
3024 $this->batch_queue[] = $batch_item;
3030 protected function convert_result($data, $method, $params) {
3031 $is_xml = (empty($params['format']) ||
3032 strtolower($params['format']) != 'json');
3033 return ($is_xml) ? $this->convert_xml_to_result($data, $method, $params)
3034 : json_decode($data, true);
3038 * Change the response format
3040 * @param string $format The response format (json, xml)
3042 public function setFormat($format) {
3043 $this->format = $format;
3048 * get the current response serialization format
3050 * @return string 'xml', 'json', or null (which means 'xml')
3052 public function getFormat() {
3053 return $this->format;
3057 * Calls the specified file-upload POST method with the specified parameters
3059 * @param string $method Name of the Facebook method to invoke
3060 * @param array $params A map of param names => param values
3061 * @param string $file A path to the file to upload (required)
3063 * @return array A dictionary representing the response.
3065 public function call_upload_method($method, $params, $file, $server_addr = null) {
3066 if (!$this->pending_batch()) {
3067 if (!file_exists($file)) {
3069 FacebookAPIErrorCodes::API_EC_PARAM;
3070 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
3071 throw new FacebookRestClientException($description, $code);
3074 if ($this->format) {
3075 $params['format'] = $this->format;
3077 $data = $this->post_upload_request($method,
3081 $result = $this->convert_result($data, $method, $params);
3083 if (is_array($result) && isset($result['error_code'])) {
3084 throw new FacebookRestClientException($result['error_msg'],
3085 $result['error_code']);
3090 FacebookAPIErrorCodes::API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE;
3091 $description = FacebookAPIErrorCodes::$api_error_descriptions[$code];
3092 throw new FacebookRestClientException($description, $code);
3098 protected function convert_xml_to_result($xml, $method, $params) {
3099 $sxml = simplexml_load_string($xml);
3100 $result = self::convert_simplexml_to_array($sxml);
3102 if (!empty($GLOBALS['facebook_config']['debug'])) {
3103 // output the raw xml and its corresponding php object, for debugging:
3104 print '<div style="margin: 10px 30px; padding: 5px; border: 2px solid black; background: gray; color: white; font-size: 12px; font-weight: bold;">';
3106 print $this->cur_id . ': Called ' . $method . ', show ' .
3107 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'params\');">Params</a> | '.
3108 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'xml\');">XML</a> | '.
3109 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'sxml\');">SXML</a> | '.
3110 '<a href=# onclick="return toggleDisplay(' . $this->cur_id . ', \'php\');">PHP</a>';
3111 print '<pre id="params'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($params, true).'</pre>';
3112 print '<pre id="xml'.$this->cur_id.'" style="display: none; overflow: auto;">'.htmlspecialchars($xml).'</pre>';
3113 print '<pre id="php'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($result, true).'</pre>';
3114 print '<pre id="sxml'.$this->cur_id.'" style="display: none; overflow: auto;">'.print_r($sxml, true).'</pre>';
3120 protected function finalize_params($method, $params) {
3121 list($get, $post) = $this->add_standard_params($method, $params);
3122 // we need to do this before signing the params
3123 $this->convert_array_values_to_json($post);
3124 $post['sig'] = Facebook::generate_sig(array_merge($get, $post),
3126 return array($get, $post);
3129 private function convert_array_values_to_json(&$params) {
3130 foreach ($params as $key => &$val) {
3131 if (is_array($val)) {
3132 $val = json_encode($val);
3138 * Add the generally required params to our request.
3139 * Params method, api_key, and v should be sent over as get.
3141 private function add_standard_params($method, $params) {
3144 if ($this->call_as_apikey) {
3145 $get['call_as_apikey'] = $this->call_as_apikey;
3147 $get['method'] = $method;
3148 $get['session_key'] = $this->session_key;
3149 $get['api_key'] = $this->api_key;
3150 $post['call_id'] = microtime(true);
3151 if ($post['call_id'] <= $this->last_call_id) {
3152 $post['call_id'] = $this->last_call_id + 0.001;
3154 $this->last_call_id = $post['call_id'];
3155 if (isset($post['v'])) {
3156 $get['v'] = $post['v'];
3161 if (isset($this->use_ssl_resources) &&
3162 $this->use_ssl_resources) {
3163 $post['return_ssl_resources'] = true;
3165 return array($get, $post);
3168 private function create_url_string($params) {
3169 $post_params = array();
3170 foreach ($params as $key => &$val) {
3171 $post_params[] = $key.'='.urlencode($val);
3173 return implode('&', $post_params);
3176 private function run_multipart_http_transaction($method, $params, $file, $server_addr) {
3178 // the format of this message is specified in RFC1867/RFC1341.
3179 // we add twenty pseudo-random digits to the end of the boundary string.
3180 $boundary = '--------------------------FbMuLtIpArT' .
3181 sprintf("%010d", mt_rand()) .
3182 sprintf("%010d", mt_rand());
3183 $content_type = 'multipart/form-data; boundary=' . $boundary;
3184 // within the message, we prepend two extra hyphens.
3185 $delimiter = '--' . $boundary;
3186 $close_delimiter = $delimiter . '--';
3187 $content_lines = array();
3188 foreach ($params as $key => &$val) {
3189 $content_lines[] = $delimiter;
3190 $content_lines[] = 'Content-Disposition: form-data; name="' . $key . '"';
3191 $content_lines[] = '';
3192 $content_lines[] = $val;
3194 // now add the file data
3195 $content_lines[] = $delimiter;
3197 'Content-Disposition: form-data; filename="' . $file . '"';
3198 $content_lines[] = 'Content-Type: application/octet-stream';
3199 $content_lines[] = '';
3200 $content_lines[] = file_get_contents($file);
3201 $content_lines[] = $close_delimiter;
3202 $content_lines[] = '';
3203 $content = implode("\r\n", $content_lines);
3204 return $this->run_http_post_transaction($content_type, $content, $server_addr);
3207 public function post_request($method, $params) {
3208 list($get, $post) = $this->finalize_params($method, $params);
3209 $post_string = $this->create_url_string($post);
3210 $get_string = $this->create_url_string($get);
3211 $url_with_get = $this->server_addr . '?' . $get_string;
3212 if ($this->use_curl_if_available && function_exists('curl_init')) {
3213 $useragent = 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion();
3215 curl_setopt($ch, CURLOPT_URL, $url_with_get);
3216 curl_setopt($ch, CURLOPT_POSTFIELDS, $post_string);
3217 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
3218 curl_setopt($ch, CURLOPT_USERAGENT, $useragent);
3219 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
3220 curl_setopt($ch, CURLOPT_TIMEOUT, 30);
3221 $result = $this->curl_exec($ch);
3224 $content_type = 'application/x-www-form-urlencoded';
3225 $content = $post_string;
3226 $result = $this->run_http_post_transaction($content_type,
3234 * execute a curl transaction -- this exists mostly so subclasses can add
3235 * extra options and/or process the response, if they wish.
3237 * @param resource $ch a curl handle
3239 protected function curl_exec($ch) {
3240 $result = curl_exec($ch);
3244 private function post_upload_request($method, $params, $file, $server_addr = null) {
3245 $server_addr = $server_addr ? $server_addr : $this->server_addr;
3246 list($get, $post) = $this->finalize_params($method, $params);
3247 $get_string = $this->create_url_string($get);
3248 $url_with_get = $server_addr . '?' . $get_string;
3249 if ($this->use_curl_if_available && function_exists('curl_init')) {
3250 // prepending '@' causes cURL to upload the file; the key is ignored.
3251 $post['_file'] = '@' . $file;
3252 $useragent = 'Facebook API PHP5 Client 1.1 (curl) ' . phpversion();
3254 curl_setopt($ch, CURLOPT_URL, $url_with_get);
3255 // this has to come before the POSTFIELDS set!
3256 curl_setopt($ch, CURLOPT_POST, 1);
3257 // passing an array gets curl to use the multipart/form-data content type
3258 curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
3259 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
3260 curl_setopt($ch, CURLOPT_USERAGENT, $useragent);
3261 $result = $this->curl_exec($ch);
3264 $result = $this->run_multipart_http_transaction($method, $post,
3265 $file, $url_with_get);
3270 private function run_http_post_transaction($content_type, $content, $server_addr) {
3272 $user_agent = 'Facebook API PHP5 Client 1.1 (non-curl) ' . phpversion();
3273 $content_length = strlen($content);
3276 array('method' => 'POST',
3277 'user_agent' => $user_agent,
3278 'header' => 'Content-Type: ' . $content_type . "\r\n" .
3279 'Content-Length: ' . $content_length,
3280 'content' => $content));
3281 $context_id = stream_context_create($context);
3282 $sock = fopen($server_addr, 'r', false, $context_id);
3286 while (!feof($sock)) {
3287 $result .= fgets($sock, 4096);
3294 public static function convert_simplexml_to_array($sxml) {
3297 foreach ($sxml as $k => $v) {
3298 if ($sxml['list']) {
3299 $arr[] = self::convert_simplexml_to_array($v);
3301 $arr[$k] = self::convert_simplexml_to_array($v);
3305 if (sizeof($arr) > 0) {
3308 return (string)$sxml;
3312 protected function get_uid($uid) {
3313 return $uid ? $uid : $this->user;
3318 class FacebookRestClientException extends Exception {
3321 // Supporting methods and values------
3324 * Error codes and descriptions for the Facebook API.
3327 class FacebookAPIErrorCodes {
3329 const API_EC_SUCCESS = 0;
3334 const API_EC_UNKNOWN = 1;
3335 const API_EC_SERVICE = 2;
3336 const API_EC_METHOD = 3;
3337 const API_EC_TOO_MANY_CALLS = 4;
3338 const API_EC_BAD_IP = 5;
3339 const API_EC_HOST_API = 6;
3340 const API_EC_HOST_UP = 7;
3341 const API_EC_SECURE = 8;
3342 const API_EC_RATE = 9;
3343 const API_EC_PERMISSION_DENIED = 10;
3344 const API_EC_DEPRECATED = 11;
3345 const API_EC_VERSION = 12;
3346 const API_EC_INTERNAL_FQL_ERROR = 13;
3347 const API_EC_HOST_PUP = 14;
3352 const API_EC_PARAM = 100;
3353 const API_EC_PARAM_API_KEY = 101;
3354 const API_EC_PARAM_SESSION_KEY = 102;
3355 const API_EC_PARAM_CALL_ID = 103;
3356 const API_EC_PARAM_SIGNATURE = 104;
3357 const API_EC_PARAM_TOO_MANY = 105;
3358 const API_EC_PARAM_USER_ID = 110;
3359 const API_EC_PARAM_USER_FIELD = 111;
3360 const API_EC_PARAM_SOCIAL_FIELD = 112;
3361 const API_EC_PARAM_EMAIL = 113;
3362 const API_EC_PARAM_USER_ID_LIST = 114;
3363 const API_EC_PARAM_FIELD_LIST = 115;
3364 const API_EC_PARAM_ALBUM_ID = 120;
3365 const API_EC_PARAM_PHOTO_ID = 121;
3366 const API_EC_PARAM_FEED_PRIORITY = 130;
3367 const API_EC_PARAM_CATEGORY = 140;
3368 const API_EC_PARAM_SUBCATEGORY = 141;
3369 const API_EC_PARAM_TITLE = 142;
3370 const API_EC_PARAM_DESCRIPTION = 143;
3371 const API_EC_PARAM_BAD_JSON = 144;
3372 const API_EC_PARAM_BAD_EID = 150;
3373 const API_EC_PARAM_UNKNOWN_CITY = 151;
3374 const API_EC_PARAM_BAD_PAGE_TYPE = 152;
3377 * USER PERMISSIONS ERRORS
3379 const API_EC_PERMISSION = 200;
3380 const API_EC_PERMISSION_USER = 210;
3381 const API_EC_PERMISSION_NO_DEVELOPERS = 211;
3382 const API_EC_PERMISSION_OFFLINE_ACCESS = 212;
3383 const API_EC_PERMISSION_ALBUM = 220;
3384 const API_EC_PERMISSION_PHOTO = 221;
3385 const API_EC_PERMISSION_MESSAGE = 230;
3386 const API_EC_PERMISSION_OTHER_USER = 240;
3387 const API_EC_PERMISSION_STATUS_UPDATE = 250;
3388 const API_EC_PERMISSION_PHOTO_UPLOAD = 260;
3389 const API_EC_PERMISSION_VIDEO_UPLOAD = 261;
3390 const API_EC_PERMISSION_SMS = 270;
3391 const API_EC_PERMISSION_CREATE_LISTING = 280;
3392 const API_EC_PERMISSION_CREATE_NOTE = 281;
3393 const API_EC_PERMISSION_SHARE_ITEM = 282;
3394 const API_EC_PERMISSION_EVENT = 290;
3395 const API_EC_PERMISSION_LARGE_FBML_TEMPLATE = 291;
3396 const API_EC_PERMISSION_LIVEMESSAGE = 292;
3397 const API_EC_PERMISSION_RSVP_EVENT = 299;
3402 const API_EC_EDIT = 300;
3403 const API_EC_EDIT_USER_DATA = 310;
3404 const API_EC_EDIT_PHOTO = 320;
3405 const API_EC_EDIT_ALBUM_SIZE = 321;
3406 const API_EC_EDIT_PHOTO_TAG_SUBJECT = 322;
3407 const API_EC_EDIT_PHOTO_TAG_PHOTO = 323;
3408 const API_EC_EDIT_PHOTO_FILE = 324;
3409 const API_EC_EDIT_PHOTO_PENDING_LIMIT = 325;
3410 const API_EC_EDIT_PHOTO_TAG_LIMIT = 326;
3411 const API_EC_EDIT_ALBUM_REORDER_PHOTO_NOT_IN_ALBUM = 327;
3412 const API_EC_EDIT_ALBUM_REORDER_TOO_FEW_PHOTOS = 328;
3414 const API_EC_MALFORMED_MARKUP = 329;
3415 const API_EC_EDIT_MARKUP = 330;
3417 const API_EC_EDIT_FEED_TOO_MANY_USER_CALLS = 340;
3418 const API_EC_EDIT_FEED_TOO_MANY_USER_ACTION_CALLS = 341;
3419 const API_EC_EDIT_FEED_TITLE_LINK = 342;
3420 const API_EC_EDIT_FEED_TITLE_LENGTH = 343;
3421 const API_EC_EDIT_FEED_TITLE_NAME = 344;
3422 const API_EC_EDIT_FEED_TITLE_BLANK = 345;
3423 const API_EC_EDIT_FEED_BODY_LENGTH = 346;
3424 const API_EC_EDIT_FEED_PHOTO_SRC = 347;
3425 const API_EC_EDIT_FEED_PHOTO_LINK = 348;
3427 const API_EC_EDIT_VIDEO_SIZE = 350;
3428 const API_EC_EDIT_VIDEO_INVALID_FILE = 351;
3429 const API_EC_EDIT_VIDEO_INVALID_TYPE = 352;
3430 const API_EC_EDIT_VIDEO_FILE = 353;
3432 const API_EC_EDIT_FEED_TITLE_ARRAY = 360;
3433 const API_EC_EDIT_FEED_TITLE_PARAMS = 361;
3434 const API_EC_EDIT_FEED_BODY_ARRAY = 362;
3435 const API_EC_EDIT_FEED_BODY_PARAMS = 363;
3436 const API_EC_EDIT_FEED_PHOTO = 364;
3437 const API_EC_EDIT_FEED_TEMPLATE = 365;
3438 const API_EC_EDIT_FEED_TARGET = 366;
3439 const API_EC_EDIT_FEED_MARKUP = 367;
3444 const API_EC_SESSION_TIMED_OUT = 450;
3445 const API_EC_SESSION_METHOD = 451;
3446 const API_EC_SESSION_INVALID = 452;
3447 const API_EC_SESSION_REQUIRED = 453;
3448 const API_EC_SESSION_REQUIRED_FOR_SECRET = 454;
3449 const API_EC_SESSION_CANNOT_USE_SESSION_SECRET = 455;
3455 const FQL_EC_UNKNOWN_ERROR = 600;
3456 const FQL_EC_PARSER = 601; // backwards compatibility
3457 const FQL_EC_PARSER_ERROR = 601;
3458 const FQL_EC_UNKNOWN_FIELD = 602;
3459 const FQL_EC_UNKNOWN_TABLE = 603;
3460 const FQL_EC_NOT_INDEXABLE = 604; // backwards compatibility
3461 const FQL_EC_NO_INDEX = 604;
3462 const FQL_EC_UNKNOWN_FUNCTION = 605;
3463 const FQL_EC_INVALID_PARAM = 606;
3464 const FQL_EC_INVALID_FIELD = 607;
3465 const FQL_EC_INVALID_SESSION = 608;
3466 const FQL_EC_UNSUPPORTED_APP_TYPE = 609;
3467 const FQL_EC_SESSION_SECRET_NOT_ALLOWED = 610;
3468 const FQL_EC_DEPRECATED_TABLE = 611;
3469 const FQL_EC_EXTENDED_PERMISSION = 612;
3470 const FQL_EC_RATE_LIMIT_EXCEEDED = 613;
3471 const FQL_EC_UNRESOLVED_DEPENDENCY = 614;
3473 const API_EC_REF_SET_FAILED = 700;
3476 * DATA STORE API ERRORS
3478 const API_EC_DATA_UNKNOWN_ERROR = 800;
3479 const API_EC_DATA_INVALID_OPERATION = 801;
3480 const API_EC_DATA_QUOTA_EXCEEDED = 802;
3481 const API_EC_DATA_OBJECT_NOT_FOUND = 803;
3482 const API_EC_DATA_OBJECT_ALREADY_EXISTS = 804;
3483 const API_EC_DATA_DATABASE_ERROR = 805;
3484 const API_EC_DATA_CREATE_TEMPLATE_ERROR = 806;
3485 const API_EC_DATA_TEMPLATE_EXISTS_ERROR = 807;
3486 const API_EC_DATA_TEMPLATE_HANDLE_TOO_LONG = 808;
3487 const API_EC_DATA_TEMPLATE_HANDLE_ALREADY_IN_USE = 809;
3488 const API_EC_DATA_TOO_MANY_TEMPLATE_BUNDLES = 810;
3489 const API_EC_DATA_MALFORMED_ACTION_LINK = 811;
3490 const API_EC_DATA_TEMPLATE_USES_RESERVED_TOKEN = 812;
3493 * APPLICATION INFO ERRORS
3495 const API_EC_NO_SUCH_APP = 900;
3500 const API_EC_BATCH_TOO_MANY_ITEMS = 950;
3501 const API_EC_BATCH_ALREADY_STARTED = 951;
3502 const API_EC_BATCH_NOT_STARTED = 952;
3503 const API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE = 953;
3508 const API_EC_EVENT_INVALID_TIME = 1000;
3513 const API_EC_INFO_NO_INFORMATION = 1050;
3514 const API_EC_INFO_SET_FAILED = 1051;
3517 * LIVEMESSAGE API ERRORS
3519 const API_EC_LIVEMESSAGE_SEND_FAILED = 1100;
3520 const API_EC_LIVEMESSAGE_EVENT_NAME_TOO_LONG = 1101;
3521 const API_EC_LIVEMESSAGE_MESSAGE_TOO_LONG = 1102;
3524 * PAYMENTS API ERRORS
3526 const API_EC_PAYMENTS_UNKNOWN = 1150;
3527 const API_EC_PAYMENTS_APP_INVALID = 1151;
3528 const API_EC_PAYMENTS_DATABASE = 1152;
3529 const API_EC_PAYMENTS_PERMISSION_DENIED = 1153;
3530 const API_EC_PAYMENTS_APP_NO_RESPONSE = 1154;
3531 const API_EC_PAYMENTS_APP_ERROR_RESPONSE = 1155;
3532 const API_EC_PAYMENTS_INVALID_ORDER = 1156;
3533 const API_EC_PAYMENTS_INVALID_PARAM = 1157;
3534 const API_EC_PAYMENTS_INVALID_OPERATION = 1158;
3535 const API_EC_PAYMENTS_PAYMENT_FAILED = 1159;
3536 const API_EC_PAYMENTS_DISABLED = 1160;
3539 * CONNECT SESSION ERRORS
3541 const API_EC_CONNECT_FEED_DISABLED = 1300;
3544 * Platform tag bundles errors
3546 const API_EC_TAG_BUNDLE_QUOTA = 1400;
3551 const API_EC_SHARE_BAD_URL = 1500;
3556 const API_EC_NOTE_CANNOT_MODIFY = 1600;
3561 const API_EC_COMMENTS_UNKNOWN = 1700;
3562 const API_EC_COMMENTS_POST_TOO_LONG = 1701;
3563 const API_EC_COMMENTS_DB_DOWN = 1702;
3564 const API_EC_COMMENTS_INVALID_XID = 1703;
3565 const API_EC_COMMENTS_INVALID_UID = 1704;
3566 const API_EC_COMMENTS_INVALID_POST = 1705;
3567 const API_EC_COMMENTS_INVALID_REMOVE = 1706;
3570 * This array is no longer maintained; to view the description of an error
3571 * code, please look at the message element of the API response or visit
3572 * the developer wiki at http://wiki.developers.facebook.com/.
3574 public static $api_error_descriptions = array(
3575 self::API_EC_SUCCESS => 'Success',
3576 self::API_EC_UNKNOWN => 'An unknown error occurred',
3577 self::API_EC_SERVICE => 'Service temporarily unavailable',
3578 self::API_EC_METHOD => 'Unknown method',
3579 self::API_EC_TOO_MANY_CALLS => 'Application request limit reached',
3580 self::API_EC_BAD_IP => 'Unauthorized source IP address',
3581 self::API_EC_PARAM => 'Invalid parameter',
3582 self::API_EC_PARAM_API_KEY => 'Invalid API key',
3583 self::API_EC_PARAM_SESSION_KEY => 'Session key invalid or no longer valid',
3584 self::API_EC_PARAM_CALL_ID => 'Call_id must be greater than previous',
3585 self::API_EC_PARAM_SIGNATURE => 'Incorrect signature',
3586 self::API_EC_PARAM_USER_ID => 'Invalid user id',
3587 self::API_EC_PARAM_USER_FIELD => 'Invalid user info field',
3588 self::API_EC_PARAM_SOCIAL_FIELD => 'Invalid user field',
3589 self::API_EC_PARAM_USER_ID_LIST => 'Invalid user id list',
3590 self::API_EC_PARAM_FIELD_LIST => 'Invalid field list',
3591 self::API_EC_PARAM_ALBUM_ID => 'Invalid album id',
3592 self::API_EC_PARAM_BAD_EID => 'Invalid eid',
3593 self::API_EC_PARAM_UNKNOWN_CITY => 'Unknown city',
3594 self::API_EC_PERMISSION => 'Permissions error',
3595 self::API_EC_PERMISSION_USER => 'User not visible',
3596 self::API_EC_PERMISSION_NO_DEVELOPERS => 'Application has no developers',
3597 self::API_EC_PERMISSION_ALBUM => 'Album not visible',
3598 self::API_EC_PERMISSION_PHOTO => 'Photo not visible',
3599 self::API_EC_PERMISSION_EVENT => 'Creating and modifying events required the extended permission create_event',
3600 self::API_EC_PERMISSION_RSVP_EVENT => 'RSVPing to events required the extended permission rsvp_event',
3601 self::API_EC_EDIT_ALBUM_SIZE => 'Album is full',
3602 self::FQL_EC_PARSER => 'FQL: Parser Error',
3603 self::FQL_EC_UNKNOWN_FIELD => 'FQL: Unknown Field',
3604 self::FQL_EC_UNKNOWN_TABLE => 'FQL: Unknown Table',
3605 self::FQL_EC_NOT_INDEXABLE => 'FQL: Statement not indexable',
3606 self::FQL_EC_UNKNOWN_FUNCTION => 'FQL: Attempted to call unknown function',
3607 self::FQL_EC_INVALID_PARAM => 'FQL: Invalid parameter passed in',
3608 self::API_EC_DATA_UNKNOWN_ERROR => 'Unknown data store API error',
3609 self::API_EC_DATA_INVALID_OPERATION => 'Invalid operation',
3610 self::API_EC_DATA_QUOTA_EXCEEDED => 'Data store allowable quota was exceeded',
3611 self::API_EC_DATA_OBJECT_NOT_FOUND => 'Specified object cannot be found',
3612 self::API_EC_DATA_OBJECT_ALREADY_EXISTS => 'Specified object already exists',
3613 self::API_EC_DATA_DATABASE_ERROR => 'A database error occurred. Please try again',
3614 self::API_EC_BATCH_ALREADY_STARTED => 'begin_batch already called, please make sure to call end_batch first',
3615 self::API_EC_BATCH_NOT_STARTED => 'end_batch called before begin_batch',
3616 self::API_EC_BATCH_METHOD_NOT_ALLOWED_IN_BATCH_MODE => 'This method is not allowed in batch mode'