lib/apiaction.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Base API action
   6  *
   7  * PHP version 5
   8  *
   9  * LICENCE: This program is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Affero General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Affero General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Affero General Public License
  20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * @category  API
  23  * @package   StatusNet
  24  * @author    Craig Andrews <candrews@integralblue.com>
  25  * @author    Dan Moore <dan@moore.cx>
  26  * @author    Evan Prodromou <evan@status.net>
  27  * @author    Jeffery To <jeffery.to@gmail.com>
  28  * @author    Toby Inkster <mail@tobyinkster.co.uk>
  29  * @author    Zach Copley <zach@status.net>
  30  * @copyright 2009-2010 StatusNet, Inc.
  31  * @copyright 2009 Free Software Foundation, Inc http://www.fsf.org
  32  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  33  * @link      http://status.net/
  34  */
  35
  36 /* External API usage documentation. Please update when you change how the API works. */
  37
  38 /*! @mainpage StatusNet REST API
  39
  40     @section Introduction
  41
  42     Some explanatory text about the API would be nice.
  43
  44     @section API Methods
  45
  46     @subsection timelinesmethods_sec Timeline Methods
  47
  48     @li @ref publictimeline
  49     @li @ref friendstimeline
  50
  51     @subsection statusmethods_sec Status Methods
  52
  53     @li @ref statusesupdate
  54
  55     @subsection usermethods_sec User Methods
  56
  57     @subsection directmessagemethods_sec Direct Message Methods (now a plugin)
  58
  59     @subsection friendshipmethods_sec Friendship Methods
  60
  61     @subsection socialgraphmethods_sec Social Graph Methods
  62
  63     @subsection accountmethods_sec Account Methods
  64
  65     @subsection favoritesmethods_sec Favorites Methods
  66
  67     @subsection blockmethods_sec Block Methods
  68
  69     @subsection oauthmethods_sec OAuth Methods
  70
  71     @subsection helpmethods_sec Help Methods
  72
  73     @subsection groupmethods_sec Group Methods
  74
  75     @page apiroot API Root
  76
  77     The URLs for methods referred to in this API documentation are
  78     relative to the StatusNet API root. The API root is determined by the
  79     site's @b server and @b path variables, which are generally specified
  80     in config.php. For example:
  81
  82     @code
  83     $config['site']['server'] = 'example.org';
  84     $config['site']['path'] = 'statusnet'
  85     @endcode
  86
  87     The pattern for a site's API root is: @c protocol://server/path/api E.g:
  88
  89     @c http://example.org/statusnet/api
  90
  91     The @b path can be empty.  In that case the API root would simply be:
  92
  93     @c http://example.org/api
  94
  95 */
  96
  97 if (!defined('STATUSNET')) {
  98     exit(1);
  99 }
 100
 101 class ApiValidationException extends Exception { }
 102
 103 /**
 104  * Contains most of the Twitter-compatible API output functions.
 105  *
 106  * @category API
 107  * @package  StatusNet
 108  * @author   Craig Andrews <candrews@integralblue.com>
 109  * @author   Dan Moore <dan@moore.cx>
 110  * @author   Evan Prodromou <evan@status.net>
 111  * @author   Jeffery To <jeffery.to@gmail.com>
 112  * @author   Toby Inkster <mail@tobyinkster.co.uk>
 113  * @author   Zach Copley <zach@status.net>
 114  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
 115  * @link     http://status.net/
 116  */
 117 class ApiAction extends Action
 118 {
 119     const READ_ONLY  = 1;
 120     const READ_WRITE = 2;
 121
 122     var $user      = null;
 123     var $auth_user = null;
 124     var $page      = null;
 125     var $count     = null;
 126     var $offset    = null;
 127     var $limit     = null;
 128     var $max_id    = null;
 129     var $since_id  = null;
 130     var $source    = null;
 131     var $callback  = null;
 132     var $format    = null;
 133
 134     var $access    = self::READ_ONLY;  // read (default) or read-write
 135
 136     static $reserved_sources = array('web', 'omb', 'ostatus', 'mail', 'xmpp', 'api');
 137
 138     /**
 139      * Initialization.
 140      *
 141      * @param array $args Web and URL arguments
 142      *
 143      * @return boolean false if user doesn't exist
 144      */
 145     protected function prepare(array $args=array())
 146     {
 147         GNUsocial::setApi(true); // reduce exception reports to aid in debugging
 148         parent::prepare($args);
 149
 150         $this->format   = $this->arg('format');
 151         $this->callback = $this->arg('callback');
 152         $this->page     = (int)$this->arg('page', 1);
 153         $this->count    = (int)$this->arg('count', 20);
 154         $this->max_id   = (int)$this->arg('max_id', 0);
 155         $this->since_id = (int)$this->arg('since_id', 0);
 156
 157         // These two are not used everywhere, mainly just AtompubAction extensions
 158         $this->offset   = ($this->page-1) * $this->count;
 159         $this->limit    = $this->count + 1;
 160
 161         if ($this->arg('since')) {
 162             header('X-GNUsocial-Warning: since parameter is disabled; use since_id');
 163         }
 164
 165         $this->source = $this->trimmed('source');
 166
 167         if (empty($this->source) || in_array($this->source, self::$reserved_sources)) {
 168             $this->source = 'api';
 169         }
 170
 171         return true;
 172     }
 173
 174     /**
 175      * Handle a request
 176      *
 177      * @param array $args Arguments from $_REQUEST
 178      *
 179      * @return void
 180      */
 181     protected function handle()
 182     {
 183         header('Access-Control-Allow-Origin: *');
 184         parent::handle();
 185     }
 186
 187     /**
 188      * Overrides XMLOutputter::element to write booleans as strings (true|false).
 189      * See that method's documentation for more info.
 190      *
 191      * @param string $tag     Element type or tagname
 192      * @param array  $attrs   Array of element attributes, as
 193      *                        key-value pairs
 194      * @param string $content string content of the element
 195      *
 196      * @return void
 197      */
 198     function element($tag, $attrs=null, $content=null)
 199     {
 200         if (is_bool($content)) {
 201             $content = ($content ? 'true' : 'false');
 202         }
 203
 204         return parent::element($tag, $attrs, $content);
 205     }
 206
 207     function twitterUserArray($profile, $get_notice=false)
 208     {
 209         $twitter_user = array();
 210
 211         try {
 212             $user = $profile->getUser();
 213         } catch (NoSuchUserException $e) {
 214             $user = null;
 215         }
 216
 217         $twitter_user['id'] = intval($profile->id);
 218         $twitter_user['name'] = $profile->getBestName();
 219         $twitter_user['screen_name'] = $profile->nickname;
 220         $twitter_user['location'] = ($profile->location) ? $profile->location : null;
 221         $twitter_user['description'] = ($profile->bio) ? $profile->bio : null;
 222
 223         // TODO: avatar url template (example.com/user/avatar?size={x}x{y})
 224         $twitter_user['profile_image_url'] = Avatar::urlByProfile($profile, AVATAR_STREAM_SIZE);
 225         $twitter_user['profile_image_url_https'] = $twitter_user['profile_image_url'];
 226
 227         // START introduced by qvitter API, not necessary for StatusNet API
 228         $twitter_user['profile_image_url_profile_size'] = Avatar::urlByProfile($profile, AVATAR_PROFILE_SIZE);
 229         try {
 230             $avatar  = Avatar::getUploaded($profile);
 231             $origurl = $avatar->displayUrl();
 232         } catch (Exception $e) {
 233             $origurl = $twitter_user['profile_image_url_profile_size'];
 234         }
 235         $twitter_user['profile_image_url_original'] = $origurl;
 236
 237         $twitter_user['groups_count'] = $profile->getGroupCount();
 238         foreach (array('linkcolor', 'backgroundcolor') as $key) {
 239             $twitter_user[$key] = Profile_prefs::getConfigData($profile, 'theme', $key);
 240         }
 241         // END introduced by qvitter API, not necessary for StatusNet API
 242
 243         $twitter_user['url'] = ($profile->homepage) ? $profile->homepage : null;
 244         $twitter_user['protected'] = (!empty($user) && $user->private_stream) ? true : false;
 245         $twitter_user['followers_count'] = $profile->subscriberCount();
 246
 247         // Note: some profiles don't have an associated user
 248
 249         $twitter_user['friends_count'] = $profile->subscriptionCount();
 250
 251         $twitter_user['created_at'] = self::dateTwitter($profile->created);
 252
 253         $timezone = 'UTC';
 254
 255         if (!empty($user) && $user->timezone) {
 256             $timezone = $user->timezone;
 257         }
 258
 259         $t = new DateTime;
 260         $t->setTimezone(new DateTimeZone($timezone));
 261
 262         $twitter_user['utc_offset'] = $t->format('Z');
 263         $twitter_user['time_zone'] = $timezone;
 264         $twitter_user['statuses_count'] = $profile->noticeCount();
 265
 266         // Is the requesting user following this user?
 267         // These values might actually also mean "unknown". Ambiguity issues?
 268         $twitter_user['following'] = false;
 269         $twitter_user['statusnet_blocking'] = false;
 270         $twitter_user['notifications'] = false;
 271
 272         if ($this->scoped instanceof Profile) {
 273             try {
 274                 $sub = Subscription::getSubscription($this->scoped, $profile);
 275                 // Notifications on?
 276                 $twitter_user['following'] = true;
 277                 $twitter_user['notifications'] = ($sub->jabber || $sub->sms);
 278             } catch (NoResultException $e) {
 279                 // well, the values are already false...
 280             }
 281             $twitter_user['statusnet_blocking']  = $this->scoped->hasBlocked($profile);
 282         }
 283
 284         if ($get_notice) {
 285             $notice = $profile->getCurrentNotice();
 286             if ($notice instanceof Notice) {
 287                 // don't get user!
 288                 $twitter_user['status'] = $this->twitterStatusArray($notice, false);
 289             }
 290         }
 291
 292         // StatusNet-specific
 293
 294         $twitter_user['statusnet_profile_url'] = $profile->profileurl;
 295
 296         // The event call to handle NoticeSimpleStatusArray lets plugins add data to the output array
 297         Event::handle('TwitterUserArray', array($profile, &$twitter_user, $this->scoped, array()));
 298
 299         return $twitter_user;
 300     }
 301
 302     function twitterStatusArray($notice, $include_user=true)
 303     {
 304         $base = $this->twitterSimpleStatusArray($notice, $include_user);
 305
 306         // FIXME: MOVE TO SHARE PLUGIN
 307         if (!empty($notice->repeat_of)) {
 308             $original = Notice::getKV('id', $notice->repeat_of);
 309             if ($original instanceof Notice) {
 310                 $orig_array = $this->twitterSimpleStatusArray($original, $include_user);
 311                 $base['retweeted_status'] = $orig_array;
 312             }
 313         }
 314
 315         return $base;
 316     }
 317
 318     function twitterSimpleStatusArray($notice, $include_user=true)
 319     {
 320         $profile = $notice->getProfile();
 321
 322         $twitter_status = array();
 323         $twitter_status['text'] = $notice->content;
 324         $twitter_status['truncated'] = false; # Not possible on StatusNet
 325         $twitter_status['created_at'] = self::dateTwitter($notice->created);
 326         try {
 327             // We could just do $notice->reply_to but maybe the future holds a
 328             // different story for parenting.
 329             $parent = $notice->getParent();
 330             $in_reply_to = $parent->id;
 331         } catch (NoParentNoticeException $e) {
 332             $in_reply_to = null;
 333         } catch (NoResultException $e) {
 334             // the in_reply_to message has probably been deleted
 335             $in_reply_to = null;
 336         }
 337         $twitter_status['in_reply_to_status_id'] = $in_reply_to;
 338
 339         $source = null;
 340
 341         $ns = $notice->getSource();
 342         if ($ns instanceof Notice_source) {
 343             if (!empty($ns->name) && !empty($ns->url)) {
 344                 $source = '<a href="'
 345                     . htmlspecialchars($ns->url)
 346                     . '" rel="nofollow">'
 347                     . htmlspecialchars($ns->name)
 348                     . '</a>';
 349             } else {
 350                 $source = $ns->code;
 351             }
 352         }
 353
 354         $twitter_status['uri'] = $notice->getUri();
 355         $twitter_status['source'] = $source;
 356         $twitter_status['id'] = intval($notice->id);
 357
 358         $replier_profile = null;
 359
 360         if ($notice->reply_to) {
 361             $reply = Notice::getKV(intval($notice->reply_to));
 362             if ($reply) {
 363                 $replier_profile = $reply->getProfile();
 364             }
 365         }
 366
 367         $twitter_status['in_reply_to_user_id'] =
 368             ($replier_profile) ? intval($replier_profile->id) : null;
 369         $twitter_status['in_reply_to_screen_name'] =
 370             ($replier_profile) ? $replier_profile->nickname : null;
 371
 372         try {
 373             $notloc = Notice_location::locFromStored($notice);
 374             // This is the format that GeoJSON expects stuff to be in
 375             $twitter_status['geo'] = array('type' => 'Point',
 376                                            'coordinates' => array((float) $notloc->lat,
 377                                                                   (float) $notloc->lon));
 378         } catch (ServerException $e) {
 379             $twitter_status['geo'] = null;
 380         }
 381
 382         // Enclosures
 383         $attachments = $notice->attachments();
 384
 385         if (!empty($attachments)) {
 386
 387             $twitter_status['attachments'] = array();
 388
 389             foreach ($attachments as $attachment) {
 390                 try {
 391                     $enclosure_o = $attachment->getEnclosure();
 392                     $enclosure = array();
 393                     $enclosure['url'] = $enclosure_o->url;
 394                     $enclosure['mimetype'] = $enclosure_o->mimetype;
 395                     $enclosure['size'] = $enclosure_o->size;
 396                     $twitter_status['attachments'][] = $enclosure;
 397                 } catch (ServerException $e) {
 398                     // There was not enough metadata available
 399                 }
 400             }
 401         }
 402
 403         if ($include_user && $profile) {
 404             // Don't get notice (recursive!)
 405             $twitter_user = $this->twitterUserArray($profile, false);
 406             $twitter_status['user'] = $twitter_user;
 407         }
 408
 409         // StatusNet-specific
 410
 411         $twitter_status['statusnet_html'] = $notice->getRendered();
 412         $twitter_status['statusnet_conversation_id'] = intval($notice->conversation);
 413
 414         // The event call to handle NoticeSimpleStatusArray lets plugins add data to the output array
 415         Event::handle('NoticeSimpleStatusArray', array($notice, &$twitter_status, $this->scoped,
 416                                                        array('include_user'=>$include_user)));
 417
 418         return $twitter_status;
 419     }
 420
 421     function twitterGroupArray($group)
 422     {
 423         $twitter_group = array();
 424
 425         $twitter_group['id'] = intval($group->id);
 426         $twitter_group['url'] = $group->permalink();
 427         $twitter_group['nickname'] = $group->nickname;
 428         $twitter_group['fullname'] = $group->fullname;
 429
 430         if ($this->scoped instanceof Profile) {
 431             $twitter_group['member'] = $this->scoped->isMember($group);
 432             $twitter_group['blocked'] = Group_block::isBlocked(
 433                 $group,
 434                 $this->scoped
 435             );
 436         }
 437
 438         $twitter_group['admin_count'] = $group->getAdminCount();
 439         $twitter_group['member_count'] = $group->getMemberCount();
 440         $twitter_group['original_logo'] = $group->original_logo;
 441         $twitter_group['homepage_logo'] = $group->homepage_logo;
 442         $twitter_group['stream_logo'] = $group->stream_logo;
 443         $twitter_group['mini_logo'] = $group->mini_logo;
 444         $twitter_group['homepage'] = $group->homepage;
 445         $twitter_group['description'] = $group->description;
 446         $twitter_group['location'] = $group->location;
 447         $twitter_group['created'] = self::dateTwitter($group->created);
 448         $twitter_group['modified'] = self::dateTwitter($group->modified);
 449
 450         return $twitter_group;
 451     }
 452
 453     function twitterRssGroupArray($group)
 454     {
 455         $entry = array();
 456         $entry['content']=$group->description;
 457         $entry['title']=$group->nickname;
 458         $entry['link']=$group->permalink();
 459         $entry['published']=common_date_iso8601($group->created);
 460         $entry['updated']==common_date_iso8601($group->modified);
 461         $taguribase = common_config('integration', 'groupuri');
 462         $entry['id'] = "group:$groupuribase:$entry[link]";
 463
 464         $entry['description'] = $entry['content'];
 465         $entry['pubDate'] = common_date_rfc2822($group->created);
 466         $entry['guid'] = $entry['link'];
 467
 468         return $entry;
 469     }
 470
 471     function twitterListArray($list)
 472     {
 473         $profile = Profile::getKV('id', $list->tagger);
 474
 475         $twitter_list = array();
 476         $twitter_list['id'] = $list->id;
 477         $twitter_list['name'] = $list->tag;
 478         $twitter_list['full_name'] = '@'.$profile->nickname.'/'.$list->tag;;
 479         $twitter_list['slug'] = $list->tag;
 480         $twitter_list['description'] = $list->description;
 481         $twitter_list['subscriber_count'] = $list->subscriberCount();
 482         $twitter_list['member_count'] = $list->taggedCount();
 483         $twitter_list['uri'] = $list->getUri();
 484
 485         if ($this->scoped instanceof Profile) {
 486             $twitter_list['following'] = $list->hasSubscriber($this->scoped);
 487         } else {
 488             $twitter_list['following'] = false;
 489         }
 490
 491         $twitter_list['mode'] = ($list->private) ? 'private' : 'public';
 492         $twitter_list['user'] = $this->twitterUserArray($profile, false);
 493
 494         return $twitter_list;
 495     }
 496
 497     function twitterRssEntryArray($notice)
 498     {
 499         $entry = array();
 500
 501         if (Event::handle('StartRssEntryArray', array($notice, &$entry))) {
 502             $profile = $notice->getProfile();
 503
 504             // We trim() to avoid extraneous whitespace in the output
 505
 506             $entry['content'] = common_xml_safe_str(trim($notice->getRendered()));
 507             $entry['title'] = $profile->nickname . ': ' . common_xml_safe_str(trim($notice->content));
 508             $entry['link'] = common_local_url('shownotice', array('notice' => $notice->id));
 509             $entry['published'] = common_date_iso8601($notice->created);
 510
 511             $taguribase = TagURI::base();
 512             $entry['id'] = "tag:$taguribase:$entry[link]";
 513
 514             $entry['updated'] = $entry['published'];
 515             $entry['author'] = $profile->getBestName();
 516
 517             // Enclosures
 518             $attachments = $notice->attachments();
 519             $enclosures = array();
 520
 521             foreach ($attachments as $attachment) {
 522                 try {
 523                     $enclosure_o = $attachment->getEnclosure();
 524                     $enclosure = array();
 525                     $enclosure['url'] = $enclosure_o->url;
 526                     $enclosure['mimetype'] = $enclosure_o->mimetype;
 527                     $enclosure['size'] = $enclosure_o->size;
 528                     $enclosures[] = $enclosure;
 529                 } catch (ServerException $e) {
 530                     // There was not enough metadata available
 531                 }
 532             }
 533
 534             if (!empty($enclosures)) {
 535                 $entry['enclosures'] = $enclosures;
 536             }
 537
 538             // Tags/Categories
 539             $tag = new Notice_tag();
 540             $tag->notice_id = $notice->id;
 541             if ($tag->find()) {
 542                 $entry['tags']=array();
 543                 while ($tag->fetch()) {
 544                     $entry['tags'][]=$tag->tag;
 545                 }
 546             }
 547             $tag->free();
 548
 549             // RSS Item specific
 550             $entry['description'] = $entry['content'];
 551             $entry['pubDate'] = common_date_rfc2822($notice->created);
 552             $entry['guid'] = $entry['link'];
 553
 554             try {
 555                 $notloc = Notice_location::locFromStored($notice);
 556                 // This is the format that GeoJSON expects stuff to be in.
 557                 // showGeoRSS() below uses it for XML output, so we reuse it
 558                 $entry['geo'] = array('type' => 'Point',
 559                                       'coordinates' => array((float) $notloc->lat,
 560                                                              (float) $notloc->lon));
 561             } catch (ServerException $e) {
 562                 $entry['geo'] = null;
 563             }
 564
 565             Event::handle('EndRssEntryArray', array($notice, &$entry));
 566         }
 567
 568         return $entry;
 569     }
 570
 571     function twitterRelationshipArray($source, $target)
 572     {
 573         $relationship = array();
 574
 575         $relationship['source'] =
 576             $this->relationshipDetailsArray($source->getProfile(), $target->getProfile());
 577         $relationship['target'] =
 578             $this->relationshipDetailsArray($target->getProfile(), $source->getProfile());
 579
 580         return array('relationship' => $relationship);
 581     }
 582
 583     function relationshipDetailsArray(Profile $source, Profile $target)
 584     {
 585         $details = array();
 586
 587         $details['screen_name'] = $source->getNickname();
 588         $details['followed_by'] = $target->isSubscribed($source);
 589
 590         try {
 591             $sub = Subscription::getSubscription($source, $target);
 592             $details['following'] = true;
 593             $details['notifications_enabled'] = ($sub->jabber || $sub->sms);
 594         } catch (NoResultException $e) {
 595             $details['following'] = false;
 596             $details['notifications_enabled'] = false;
 597         }
 598
 599         $details['blocking'] = $source->hasBlocked($target);
 600         $details['id'] = intval($source->id);
 601
 602         return $details;
 603     }
 604
 605     function showTwitterXmlRelationship($relationship)
 606     {
 607         $this->elementStart('relationship');
 608
 609         foreach($relationship as $element => $value) {
 610             if ($element == 'source' || $element == 'target') {
 611                 $this->elementStart($element);
 612                 $this->showXmlRelationshipDetails($value);
 613                 $this->elementEnd($element);
 614             }
 615         }
 616
 617         $this->elementEnd('relationship');
 618     }
 619
 620     function showXmlRelationshipDetails($details)
 621     {
 622         foreach($details as $element => $value) {
 623             $this->element($element, null, $value);
 624         }
 625     }
 626
 627     function showTwitterXmlStatus($twitter_status, $tag='status', $namespaces=false)
 628     {
 629         $attrs = array();
 630         if ($namespaces) {
 631             $attrs['xmlns:statusnet'] = 'http://status.net/schema/api/1/';
 632         }
 633         $this->elementStart($tag, $attrs);
 634         foreach($twitter_status as $element => $value) {
 635             switch ($element) {
 636             case 'user':
 637                 $this->showTwitterXmlUser($twitter_status['user']);
 638                 break;
 639             case 'text':
 640                 $this->element($element, null, common_xml_safe_str($value));
 641                 break;
 642             case 'attachments':
 643                 $this->showXmlAttachments($twitter_status['attachments']);
 644                 break;
 645             case 'geo':
 646                 $this->showGeoXML($value);
 647                 break;
 648             case 'retweeted_status':
 649                 // FIXME: MOVE TO SHARE PLUGIN
 650                 $this->showTwitterXmlStatus($value, 'retweeted_status');
 651                 break;
 652             default:
 653                 if (strncmp($element, 'statusnet_', 10) == 0) {
 654                     if ($element === 'statusnet_in_groups' && is_array($value)) {
 655                         // QVITTERFIX because it would cause an array to be sent as $value
 656                         // THIS IS UNDOCUMENTED AND SHOULD NEVER BE RELIED UPON (qvitter uses json output)
 657                         $value = json_encode($value);
 658                     }
 659                     $this->element('statusnet:'.substr($element, 10), null, $value);
 660                 } else {
 661                     $this->element($element, null, $value);
 662                 }
 663             }
 664         }
 665         $this->elementEnd($tag);
 666     }
 667
 668     function showTwitterXmlGroup($twitter_group)
 669     {
 670         $this->elementStart('group');
 671         foreach($twitter_group as $element => $value) {
 672             $this->element($element, null, $value);
 673         }
 674         $this->elementEnd('group');
 675     }
 676
 677     function showTwitterXmlList($twitter_list)
 678     {
 679         $this->elementStart('list');
 680         foreach($twitter_list as $element => $value) {
 681             if($element == 'user') {
 682                 $this->showTwitterXmlUser($value, 'user');
 683             }
 684             else {
 685                 $this->element($element, null, $value);
 686             }
 687         }
 688         $this->elementEnd('list');
 689     }
 690
 691     function showTwitterXmlUser($twitter_user, $role='user', $namespaces=false)
 692     {
 693         $attrs = array();
 694         if ($namespaces) {
 695             $attrs['xmlns:statusnet'] = 'http://status.net/schema/api/1/';
 696         }
 697         $this->elementStart($role, $attrs);
 698         foreach($twitter_user as $element => $value) {
 699             if ($element == 'status') {
 700                 $this->showTwitterXmlStatus($twitter_user['status']);
 701             } else if (strncmp($element, 'statusnet_', 10) == 0) {
 702                 $this->element('statusnet:'.substr($element, 10), null, $value);
 703             } else {
 704                 $this->element($element, null, $value);
 705             }
 706         }
 707         $this->elementEnd($role);
 708     }
 709
 710     function showXmlAttachments($attachments) {
 711         if (!empty($attachments)) {
 712             $this->elementStart('attachments', array('type' => 'array'));
 713             foreach ($attachments as $attachment) {
 714                 $attrs = array();
 715                 $attrs['url'] = $attachment['url'];
 716                 $attrs['mimetype'] = $attachment['mimetype'];
 717                 $attrs['size'] = $attachment['size'];
 718                 $this->element('enclosure', $attrs, '');
 719             }
 720             $this->elementEnd('attachments');
 721         }
 722     }
 723
 724     function showGeoXML($geo)
 725     {
 726         if (empty($geo)) {
 727             // empty geo element
 728             $this->element('geo');
 729         } else {
 730             $this->elementStart('geo', array('xmlns:georss' => 'http://www.georss.org/georss'));
 731             $this->element('georss:point', null, $geo['coordinates'][0] . ' ' . $geo['coordinates'][1]);
 732             $this->elementEnd('geo');
 733         }
 734     }
 735
 736     function showGeoRSS($geo)
 737     {
 738         if (!empty($geo)) {
 739             $this->element(
 740                 'georss:point',
 741                 null,
 742                 $geo['coordinates'][0] . ' ' . $geo['coordinates'][1]
 743             );
 744         }
 745     }
 746
 747     function showTwitterRssItem($entry)
 748     {
 749         $this->elementStart('item');
 750         $this->element('title', null, $entry['title']);
 751         $this->element('description', null, $entry['description']);
 752         $this->element('pubDate', null, $entry['pubDate']);
 753         $this->element('guid', null, $entry['guid']);
 754         $this->element('link', null, $entry['link']);
 755
 756         // RSS only supports 1 enclosure per item
 757         if(array_key_exists('enclosures', $entry) and !empty($entry['enclosures'])){
 758             $enclosure = $entry['enclosures'][0];
 759             $this->element('enclosure', array('url'=>$enclosure['url'],'type'=>$enclosure['mimetype'],'length'=>$enclosure['size']), null);
 760         }
 761
 762         if(array_key_exists('tags', $entry)){
 763             foreach($entry['tags'] as $tag){
 764                 $this->element('category', null,$tag);
 765             }
 766         }
 767
 768         $this->showGeoRSS($entry['geo']);
 769         $this->elementEnd('item');
 770     }
 771
 772     function showJsonObjects($objects)
 773     {
 774         print(json_encode($objects));
 775     }
 776
 777     function showSingleXmlStatus($notice)
 778     {
 779         $this->initDocument('xml');
 780         $twitter_status = $this->twitterStatusArray($notice);
 781         $this->showTwitterXmlStatus($twitter_status, 'status', true);
 782         $this->endDocument('xml');
 783     }
 784
 785     function showSingleAtomStatus($notice)
 786     {
 787         header('Content-Type: application/atom+xml; charset=utf-8');
 788         print $notice->asAtomEntry(true, true, true, $this->scoped);
 789     }
 790
 791     function show_single_json_status($notice)
 792     {
 793         $this->initDocument('json');
 794         $status = $this->twitterStatusArray($notice);
 795         $this->showJsonObjects($status);
 796         $this->endDocument('json');
 797     }
 798
 799     function showXmlTimeline($notice)
 800     {
 801         $this->initDocument('xml');
 802         $this->elementStart('statuses', array('type' => 'array',
 803                                               'xmlns:statusnet' => 'http://status.net/schema/api/1/'));
 804
 805         if (is_array($notice)) {
 806             //FIXME: make everything calling showJsonTimeline use only Notice objects
 807             $ids = array();
 808             foreach ($notice as $n) {
 809                 $ids[] = $n->getID();
 810             }
 811             $notice = Notice::multiGet('id', $ids);
 812         }
 813
 814         while ($notice->fetch()) {
 815             try {
 816                 $twitter_status = $this->twitterStatusArray($notice);
 817                 $this->showTwitterXmlStatus($twitter_status);
 818             } catch (Exception $e) {
 819                 common_log(LOG_ERR, $e->getMessage());
 820                 continue;
 821             }
 822         }
 823
 824         $this->elementEnd('statuses');
 825         $this->endDocument('xml');
 826     }
 827
 828     function showRssTimeline($notice, $title, $link, $subtitle, $suplink = null, $logo = null, $self = null)
 829     {
 830         $this->initDocument('rss');
 831
 832         $this->element('title', null, $title);
 833         $this->element('link', null, $link);
 834
 835         if (!is_null($self)) {
 836             $this->element(
 837                 'atom:link',
 838                 array(
 839                     'type' => 'application/rss+xml',
 840                     'href' => $self,
 841                     'rel'  => 'self'
 842                 )
 843            );
 844         }
 845
 846         if (!is_null($suplink)) {
 847             // For FriendFeed's SUP protocol
 848             $this->element('link', array('xmlns' => 'http://www.w3.org/2005/Atom',
 849                                          'rel' => 'http://api.friendfeed.com/2008/03#sup',
 850                                          'href' => $suplink,
 851                                          'type' => 'application/json'));
 852         }
 853
 854         if (!is_null($logo)) {
 855             $this->elementStart('image');
 856             $this->element('link', null, $link);
 857             $this->element('title', null, $title);
 858             $this->element('url', null, $logo);
 859             $this->elementEnd('image');
 860         }
 861
 862         $this->element('description', null, $subtitle);
 863         $this->element('language', null, 'en-us');
 864         $this->element('ttl', null, '40');
 865
 866         if (is_array($notice)) {
 867             //FIXME: make everything calling showJsonTimeline use only Notice objects
 868             $ids = array();
 869             foreach ($notice as $n) {
 870                 $ids[] = $n->getID();
 871             }
 872             $notice = Notice::multiGet('id', $ids);
 873         }
 874
 875         while ($notice->fetch()) {
 876             try {
 877                 $entry = $this->twitterRssEntryArray($notice);
 878                 $this->showTwitterRssItem($entry);
 879             } catch (Exception $e) {
 880                 common_log(LOG_ERR, $e->getMessage());
 881                 // continue on exceptions
 882             }
 883         }
 884
 885         $this->endTwitterRss();
 886     }
 887
 888     function showAtomTimeline($notice, $title, $id, $link, $subtitle=null, $suplink=null, $selfuri=null, $logo=null)
 889     {
 890         $this->initDocument('atom');
 891
 892         $this->element('title', null, $title);
 893         $this->element('id', null, $id);
 894         $this->element('link', array('href' => $link, 'rel' => 'alternate', 'type' => 'text/html'), null);
 895
 896         if (!is_null($logo)) {
 897             $this->element('logo',null,$logo);
 898         }
 899
 900         if (!is_null($suplink)) {
 901             // For FriendFeed's SUP protocol
 902             $this->element('link', array('rel' => 'http://api.friendfeed.com/2008/03#sup',
 903                                          'href' => $suplink,
 904                                          'type' => 'application/json'));
 905         }
 906
 907         if (!is_null($selfuri)) {
 908             $this->element('link', array('href' => $selfuri,
 909                 'rel' => 'self', 'type' => 'application/atom+xml'), null);
 910         }
 911
 912         $this->element('updated', null, common_date_iso8601('now'));
 913         $this->element('subtitle', null, $subtitle);
 914
 915         if (is_array($notice)) {
 916             //FIXME: make everything calling showJsonTimeline use only Notice objects
 917             $ids = array();
 918             foreach ($notice as $n) {
 919                 $ids[] = $n->getID();
 920             }
 921             $notice = Notice::multiGet('id', $ids);
 922         }
 923
 924         while ($notice->fetch()) {
 925             try {
 926                 $this->raw($notice->asAtomEntry());
 927             } catch (Exception $e) {
 928                 common_log(LOG_ERR, $e->getMessage());
 929                 continue;
 930             }
 931         }
 932
 933         $this->endDocument('atom');
 934     }
 935
 936     function showRssGroups($group, $title, $link, $subtitle)
 937     {
 938         $this->initDocument('rss');
 939
 940         $this->element('title', null, $title);
 941         $this->element('link', null, $link);
 942         $this->element('description', null, $subtitle);
 943         $this->element('language', null, 'en-us');
 944         $this->element('ttl', null, '40');
 945
 946         if (is_array($group)) {
 947             foreach ($group as $g) {
 948                 $twitter_group = $this->twitterRssGroupArray($g);
 949                 $this->showTwitterRssItem($twitter_group);
 950             }
 951         } else {
 952             while ($group->fetch()) {
 953                 $twitter_group = $this->twitterRssGroupArray($group);
 954                 $this->showTwitterRssItem($twitter_group);
 955             }
 956         }
 957
 958         $this->endTwitterRss();
 959     }
 960
 961     function showTwitterAtomEntry($entry)
 962     {
 963         $this->elementStart('entry');
 964         $this->element('title', null, common_xml_safe_str($entry['title']));
 965         $this->element(
 966             'content',
 967             array('type' => 'html'),
 968             common_xml_safe_str($entry['content'])
 969         );
 970         $this->element('id', null, $entry['id']);
 971         $this->element('published', null, $entry['published']);
 972         $this->element('updated', null, $entry['updated']);
 973         $this->element('link', array('type' => 'text/html',
 974                                      'href' => $entry['link'],
 975                                      'rel' => 'alternate'));
 976         $this->element('link', array('type' => $entry['avatar-type'],
 977                                      'href' => $entry['avatar'],
 978                                      'rel' => 'image'));
 979         $this->elementStart('author');
 980
 981         $this->element('name', null, $entry['author-name']);
 982         $this->element('uri', null, $entry['author-uri']);
 983
 984         $this->elementEnd('author');
 985         $this->elementEnd('entry');
 986     }
 987
 988     function showAtomGroups($group, $title, $id, $link, $subtitle=null, $selfuri=null)
 989     {
 990         $this->initDocument('atom');
 991
 992         $this->element('title', null, common_xml_safe_str($title));
 993         $this->element('id', null, $id);
 994         $this->element('link', array('href' => $link, 'rel' => 'alternate', 'type' => 'text/html'), null);
 995
 996         if (!is_null($selfuri)) {
 997             $this->element('link', array('href' => $selfuri,
 998                 'rel' => 'self', 'type' => 'application/atom+xml'), null);
 999         }
1000
1001         $this->element('updated', null, common_date_iso8601('now'));
1002         $this->element('subtitle', null, common_xml_safe_str($subtitle));
1003
1004         if (is_array($group)) {
1005             foreach ($group as $g) {
1006                 $this->raw($g->asAtomEntry());
1007             }
1008         } else {
1009             while ($group->fetch()) {
1010                 $this->raw($group->asAtomEntry());
1011             }
1012         }
1013
1014         $this->endDocument('atom');
1015
1016     }
1017
1018     function showJsonTimeline($notice)
1019     {
1020         $this->initDocument('json');
1021
1022         $statuses = array();
1023
1024         if (is_array($notice)) {
1025             //FIXME: make everything calling showJsonTimeline use only Notice objects
1026             $ids = array();
1027             foreach ($notice as $n) {
1028                 $ids[] = $n->getID();
1029             }
1030             $notice = Notice::multiGet('id', $ids);
1031         }
1032
1033         while ($notice->fetch()) {
1034             try {
1035                 $twitter_status = $this->twitterStatusArray($notice);
1036                 array_push($statuses, $twitter_status);
1037             } catch (Exception $e) {
1038                 common_log(LOG_ERR, $e->getMessage());
1039                 continue;
1040             }
1041         }
1042
1043         $this->showJsonObjects($statuses);
1044
1045         $this->endDocument('json');
1046     }
1047
1048     function showJsonGroups($group)
1049     {
1050         $this->initDocument('json');
1051
1052         $groups = array();
1053
1054         if (is_array($group)) {
1055             foreach ($group as $g) {
1056                 $twitter_group = $this->twitterGroupArray($g);
1057                 array_push($groups, $twitter_group);
1058             }
1059         } else {
1060             while ($group->fetch()) {
1061                 $twitter_group = $this->twitterGroupArray($group);
1062                 array_push($groups, $twitter_group);
1063             }
1064         }
1065
1066         $this->showJsonObjects($groups);
1067
1068         $this->endDocument('json');
1069     }
1070
1071     function showXmlGroups($group)
1072     {
1073
1074         $this->initDocument('xml');
1075         $this->elementStart('groups', array('type' => 'array'));
1076
1077         if (is_array($group)) {
1078             foreach ($group as $g) {
1079                 $twitter_group = $this->twitterGroupArray($g);
1080                 $this->showTwitterXmlGroup($twitter_group);
1081             }
1082         } else {
1083             while ($group->fetch()) {
1084                 $twitter_group = $this->twitterGroupArray($group);
1085                 $this->showTwitterXmlGroup($twitter_group);
1086             }
1087         }
1088
1089         $this->elementEnd('groups');
1090         $this->endDocument('xml');
1091     }
1092
1093     function showXmlLists($list, $next_cursor=0, $prev_cursor=0)
1094     {
1095
1096         $this->initDocument('xml');
1097         $this->elementStart('lists_list');
1098         $this->elementStart('lists', array('type' => 'array'));
1099
1100         if (is_array($list)) {
1101             foreach ($list as $l) {
1102                 $twitter_list = $this->twitterListArray($l);
1103                 $this->showTwitterXmlList($twitter_list);
1104             }
1105         } else {
1106             while ($list->fetch()) {
1107                 $twitter_list = $this->twitterListArray($list);
1108                 $this->showTwitterXmlList($twitter_list);
1109             }
1110         }
1111
1112         $this->elementEnd('lists');
1113
1114         $this->element('next_cursor', null, $next_cursor);
1115         $this->element('previous_cursor', null, $prev_cursor);
1116
1117         $this->elementEnd('lists_list');
1118         $this->endDocument('xml');
1119     }
1120
1121     function showJsonLists($list, $next_cursor=0, $prev_cursor=0)
1122     {
1123         $this->initDocument('json');
1124
1125         $lists = array();
1126
1127         if (is_array($list)) {
1128             foreach ($list as $l) {
1129                 $twitter_list = $this->twitterListArray($l);
1130                 array_push($lists, $twitter_list);
1131             }
1132         } else {
1133             while ($list->fetch()) {
1134                 $twitter_list = $this->twitterListArray($list);
1135                 array_push($lists, $twitter_list);
1136             }
1137         }
1138
1139         $lists_list = array(
1140             'lists' => $lists,
1141             'next_cursor' => $next_cursor,
1142             'next_cursor_str' => strval($next_cursor),
1143             'previous_cursor' => $prev_cursor,
1144             'previous_cursor_str' => strval($prev_cursor)
1145         );
1146
1147         $this->showJsonObjects($lists_list);
1148
1149         $this->endDocument('json');
1150     }
1151
1152     function showTwitterXmlUsers($user)
1153     {
1154         $this->initDocument('xml');
1155         $this->elementStart('users', array('type' => 'array',
1156                                            'xmlns:statusnet' => 'http://status.net/schema/api/1/'));
1157
1158         if (is_array($user)) {
1159             foreach ($user as $u) {
1160                 $twitter_user = $this->twitterUserArray($u);
1161                 $this->showTwitterXmlUser($twitter_user);
1162             }
1163         } else {
1164             while ($user->fetch()) {
1165                 $twitter_user = $this->twitterUserArray($user);
1166                 $this->showTwitterXmlUser($twitter_user);
1167             }
1168         }
1169
1170         $this->elementEnd('users');
1171         $this->endDocument('xml');
1172     }
1173
1174     function showJsonUsers($user)
1175     {
1176         $this->initDocument('json');
1177
1178         $users = array();
1179
1180         if (is_array($user)) {
1181             foreach ($user as $u) {
1182                 $twitter_user = $this->twitterUserArray($u);
1183                 array_push($users, $twitter_user);
1184             }
1185         } else {
1186             while ($user->fetch()) {
1187                 $twitter_user = $this->twitterUserArray($user);
1188                 array_push($users, $twitter_user);
1189             }
1190         }
1191
1192         $this->showJsonObjects($users);
1193
1194         $this->endDocument('json');
1195     }
1196
1197     function showSingleJsonGroup($group)
1198     {
1199         $this->initDocument('json');
1200         $twitter_group = $this->twitterGroupArray($group);
1201         $this->showJsonObjects($twitter_group);
1202         $this->endDocument('json');
1203     }
1204
1205     function showSingleXmlGroup($group)
1206     {
1207         $this->initDocument('xml');
1208         $twitter_group = $this->twitterGroupArray($group);
1209         $this->showTwitterXmlGroup($twitter_group);
1210         $this->endDocument('xml');
1211     }
1212
1213     function showSingleJsonList($list)
1214     {
1215         $this->initDocument('json');
1216         $twitter_list = $this->twitterListArray($list);
1217         $this->showJsonObjects($twitter_list);
1218         $this->endDocument('json');
1219     }
1220
1221     function showSingleXmlList($list)
1222     {
1223         $this->initDocument('xml');
1224         $twitter_list = $this->twitterListArray($list);
1225         $this->showTwitterXmlList($twitter_list);
1226         $this->endDocument('xml');
1227     }
1228
1229     static function dateTwitter($dt)
1230     {
1231         $dateStr = date('d F Y H:i:s', strtotime($dt));
1232         $d = new DateTime($dateStr, new DateTimeZone('UTC'));
1233         $d->setTimezone(new DateTimeZone(common_timezone()));
1234         return $d->format('D M d H:i:s O Y');
1235     }
1236
1237     function initDocument($type='xml')
1238     {
1239         switch ($type) {
1240         case 'xml':
1241             header('Content-Type: application/xml; charset=utf-8');
1242             $this->startXML();
1243             break;
1244         case 'json':
1245             header('Content-Type: application/json; charset=utf-8');
1246
1247             // Check for JSONP callback
1248             if (isset($this->callback)) {
1249                 print $this->callback . '(';
1250             }
1251             break;
1252         case 'rss':
1253             header("Content-Type: application/rss+xml; charset=utf-8");
1254             $this->initTwitterRss();
1255             break;
1256         case 'atom':
1257             header('Content-Type: application/atom+xml; charset=utf-8');
1258             $this->initTwitterAtom();
1259             break;
1260         default:
1261             // TRANS: Client error on an API request with an unsupported data format.
1262             $this->clientError(_('Not a supported data format.'));
1263         }
1264
1265         return;
1266     }
1267
1268     function endDocument($type='xml')
1269     {
1270         switch ($type) {
1271         case 'xml':
1272             $this->endXML();
1273             break;
1274         case 'json':
1275             // Check for JSONP callback
1276             if (isset($this->callback)) {
1277                 print ')';
1278             }
1279             break;
1280         case 'rss':
1281             $this->endTwitterRss();
1282             break;
1283         case 'atom':
1284             $this->endTwitterRss();
1285             break;
1286         default:
1287             // TRANS: Client error on an API request with an unsupported data format.
1288             $this->clientError(_('Not a supported data format.'));
1289         }
1290         return;
1291     }
1292
1293     function initTwitterRss()
1294     {
1295         $this->startXML();
1296         $this->elementStart(
1297             'rss',
1298             array(
1299                 'version'      => '2.0',
1300                 'xmlns:atom'   => 'http://www.w3.org/2005/Atom',
1301                 'xmlns:georss' => 'http://www.georss.org/georss'
1302             )
1303         );
1304         $this->elementStart('channel');
1305         Event::handle('StartApiRss', array($this));
1306     }
1307
1308     function endTwitterRss()
1309     {
1310         $this->elementEnd('channel');
1311         $this->elementEnd('rss');
1312         $this->endXML();
1313     }
1314
1315     function initTwitterAtom()
1316     {
1317         $this->startXML();
1318         // FIXME: don't hardcode the language here!
1319         $this->elementStart('feed', array('xmlns' => 'http://www.w3.org/2005/Atom',
1320                                           'xml:lang' => 'en-US',
1321                                           'xmlns:thr' => 'http://purl.org/syndication/thread/1.0'));
1322     }
1323
1324     function endTwitterAtom()
1325     {
1326         $this->elementEnd('feed');
1327         $this->endXML();
1328     }
1329
1330     function showProfile($profile, $content_type='xml', $notice=null, $includeStatuses=true)
1331     {
1332         $profile_array = $this->twitterUserArray($profile, $includeStatuses);
1333         switch ($content_type) {
1334         case 'xml':
1335             $this->showTwitterXmlUser($profile_array);
1336             break;
1337         case 'json':
1338             $this->showJsonObjects($profile_array);
1339             break;
1340         default:
1341             // TRANS: Client error on an API request with an unsupported data format.
1342             $this->clientError(_('Not a supported data format.'));
1343         }
1344         return;
1345     }
1346
1347     private static function is_decimal($str)
1348     {
1349         return preg_match('/^[0-9]+$/', $str);
1350     }
1351
1352     function getTargetUser($id)
1353     {
1354         if (empty($id)) {
1355             // Twitter supports these other ways of passing the user ID
1356             if (self::is_decimal($this->arg('id'))) {
1357                 return User::getKV($this->arg('id'));
1358             } else if ($this->arg('id')) {
1359                 $nickname = common_canonical_nickname($this->arg('id'));
1360                 return User::getKV('nickname', $nickname);
1361             } else if ($this->arg('user_id')) {
1362                 // This is to ensure that a non-numeric user_id still
1363                 // overrides screen_name even if it doesn't get used
1364                 if (self::is_decimal($this->arg('user_id'))) {
1365                     return User::getKV('id', $this->arg('user_id'));
1366                 }
1367             } else if ($this->arg('screen_name')) {
1368                 $nickname = common_canonical_nickname($this->arg('screen_name'));
1369                 return User::getKV('nickname', $nickname);
1370             } else {
1371                 // Fall back to trying the currently authenticated user
1372                 return $this->scoped->getUser();
1373             }
1374
1375         } else if (self::is_decimal($id)) {
1376             return User::getKV($id);
1377         } else {
1378             $nickname = common_canonical_nickname($id);
1379             return User::getKV('nickname', $nickname);
1380         }
1381     }
1382
1383     function getTargetProfile($id)
1384     {
1385         if (empty($id)) {
1386
1387             // Twitter supports these other ways of passing the user ID
1388             if (self::is_decimal($this->arg('id'))) {
1389                 return Profile::getKV($this->arg('id'));
1390             } else if ($this->arg('id')) {
1391                 // Screen names currently can only uniquely identify a local user.
1392                 $nickname = common_canonical_nickname($this->arg('id'));
1393                 $user = User::getKV('nickname', $nickname);
1394                 return $user ? $user->getProfile() : null;
1395             } else if ($this->arg('user_id')) {
1396                 // This is to ensure that a non-numeric user_id still
1397                 // overrides screen_name even if it doesn't get used
1398                 if (self::is_decimal($this->arg('user_id'))) {
1399                     return Profile::getKV('id', $this->arg('user_id'));
1400                 }
1401             } else if ($this->arg('screen_name')) {
1402                 $nickname = common_canonical_nickname($this->arg('screen_name'));
1403                 $user = User::getKV('nickname', $nickname);
1404                 return $user instanceof User ? $user->getProfile() : null;
1405             } else {
1406                 // Fall back to trying the currently authenticated user
1407                 return $this->scoped;
1408             }
1409         } else if (self::is_decimal($id)) {
1410             return Profile::getKV($id);
1411         } else {
1412             $nickname = common_canonical_nickname($id);
1413             $user = User::getKV('nickname', $nickname);
1414             return $user ? $user->getProfile() : null;
1415         }
1416     }
1417
1418     function getTargetGroup($id)
1419     {
1420         if (empty($id)) {
1421             if (self::is_decimal($this->arg('id'))) {
1422                 return User_group::getKV('id', $this->arg('id'));
1423             } else if ($this->arg('id')) {
1424                 return User_group::getForNickname($this->arg('id'));
1425             } else if ($this->arg('group_id')) {
1426                 // This is to ensure that a non-numeric group_id still
1427                 // overrides group_name even if it doesn't get used
1428                 if (self::is_decimal($this->arg('group_id'))) {
1429                     return User_group::getKV('id', $this->arg('group_id'));
1430                 }
1431             } else if ($this->arg('group_name')) {
1432                 return User_group::getForNickname($this->arg('group_name'));
1433             }
1434
1435         } else if (self::is_decimal($id)) {
1436             return User_group::getKV('id', $id);
1437         } else if ($this->arg('uri')) { // FIXME: move this into empty($id) check?
1438             return User_group::getKV('uri', urldecode($this->arg('uri')));
1439         } else {
1440             return User_group::getForNickname($id);
1441         }
1442     }
1443
1444     function getTargetList($user=null, $id=null)
1445     {
1446         $tagger = $this->getTargetUser($user);
1447         $list = null;
1448
1449         if (empty($id)) {
1450             $id = $this->arg('id');
1451         }
1452
1453         if($id) {
1454             if (is_numeric($id)) {
1455                 $list = Profile_list::getKV('id', $id);
1456
1457                 // only if the list with the id belongs to the tagger
1458                 if(empty($list) || $list->tagger != $tagger->id) {
1459                     $list = null;
1460                 }
1461             }
1462             if (empty($list)) {
1463                 $tag = common_canonical_tag($id);
1464                 $list = Profile_list::getByTaggerAndTag($tagger->id, $tag);
1465             }
1466
1467             if (!empty($list) && $list->private) {
1468                 if ($this->scoped->id == $list->tagger) {
1469                     return $list;
1470                 }
1471             } else {
1472                 return $list;
1473             }
1474         }
1475         return null;
1476     }
1477
1478     /**
1479      * Returns query argument or default value if not found. Certain
1480      * parameters used throughout the API are lightly scrubbed and
1481      * bounds checked.  This overrides Action::arg().
1482      *
1483      * @param string $key requested argument
1484      * @param string $def default value to return if $key is not provided
1485      *
1486      * @return var $var
1487      */
1488     function arg($key, $def=null)
1489     {
1490         // XXX: Do even more input validation/scrubbing?
1491
1492         if (array_key_exists($key, $this->args)) {
1493             switch($key) {
1494             case 'page':
1495                 $page = (int)$this->args['page'];
1496                 return ($page < 1) ? 1 : $page;
1497             case 'count':
1498                 $count = (int)$this->args['count'];
1499                 if ($count < 1) {
1500                     return 20;
1501                 } elseif ($count > 200) {
1502                     return 200;
1503                 } else {
1504                     return $count;
1505                 }
1506             case 'since_id':
1507                 $since_id = (int)$this->args['since_id'];
1508                 return ($since_id < 1) ? 0 : $since_id;
1509             case 'max_id':
1510                 $max_id = (int)$this->args['max_id'];
1511                 return ($max_id < 1) ? 0 : $max_id;
1512             default:
1513                 return parent::arg($key, $def);
1514             }
1515         } else {
1516             return $def;
1517         }
1518     }
1519
1520     /**
1521      * Calculate the complete URI that called up this action.  Used for
1522      * Atom rel="self" links.  Warning: this is funky.
1523      *
1524      * @return string URL    a URL suitable for rel="self" Atom links
1525      */
1526     function getSelfUri()
1527     {
1528         $action = mb_substr(get_class($this), 0, -6); // remove 'Action'
1529
1530         $id = $this->arg('id');
1531         $aargs = array('format' => $this->format);
1532         if (!empty($id)) {
1533             $aargs['id'] = $id;
1534         }
1535
1536         $user = $this->arg('user');
1537         if (!empty($user)) {
1538             $aargs['user'] = $user;
1539         }
1540
1541         $tag = $this->arg('tag');
1542         if (!empty($tag)) {
1543             $aargs['tag'] = $tag;
1544         }
1545
1546         parse_str($_SERVER['QUERY_STRING'], $params);
1547         $pstring = '';
1548         if (!empty($params)) {
1549             unset($params['p']);
1550             $pstring = http_build_query($params);
1551         }
1552
1553         $uri = common_local_url($action, $aargs);
1554
1555         if (!empty($pstring)) {
1556             $uri .= '?' . $pstring;
1557         }
1558
1559         return $uri;
1560     }
1561 }