actions/apitimelinefriends.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Show the friends timeline
   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    Evan Prodromou <evan@status.net>
  26  * @author    Jeffery To <jeffery.to@gmail.com>
  27  * @author    mac65 <mac65@mac65.com>
  28  * @author    Mike Cochrane <mikec@mikenz.geek.nz>
  29  * @author    Robin Millette <robin@millette.info>
  30  * @author    Zach Copley <zach@status.net>
  31  * @copyright 2009-2010 StatusNet, Inc.
  32  * @copyright 2009 Free Software Foundation, Inc http://www.fsf.org
  33  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  34  * @link      http://status.net/
  35  */
  36
  37 /* External API usage documentation. Please update when you change how this method works. */
  38
  39 /*! @page friendstimeline statuses/friends_timeline
  40
  41     @section Description
  42     Returns the 20 most recent statuses posted by the authenticating
  43     user and that user's friends. This is the equivalent of "You and
  44     friends" page in the web interface.
  45
  46     @par URL patterns
  47     @li /api/statuses/friends_timeline.:format
  48     @li /api/statuses/friends_timeline/:id.:format
  49
  50     @par Formats (:format)
  51     xml, json, rss, atom
  52
  53     @par ID (:id)
  54     username, user id
  55
  56     @par HTTP Method(s)
  57     GET
  58
  59     @par Requires Authentication
  60     Sometimes (see: @ref authentication)
  61
  62     @param user_id (Optional) Specifies a user by ID
  63     @param screen_name (Optional) Specifies a user by screename (nickname)
  64     @param since_id (Optional) Returns only statuses with an ID greater
  65     than (that is, more recent than) the specified ID.
  66     @param max_id (Optional) Returns only statuses with an ID less than
  67     (that is, older than) or equal to the specified ID.
  68     @param count (Optional) Specifies the number of statuses to retrieve.
  69     @param page (Optional) Specifies the page of results to retrieve.
  70
  71     @sa @ref authentication
  72     @sa @ref apiroot
  73
  74     @subsection usagenotes Usage notes
  75     @li The URL pattern is relative to the @ref apiroot.
  76     @li The XML response uses <a href="http://georss.org/Main_Page">GeoRSS</a>
  77     to encode the latitude and longitude (see example response below <georss:point>).
  78
  79     @subsection exampleusage Example usage
  80
  81     @verbatim
  82     curl http://identi.ca/api/statuses/friends_timeline/evan.xml?count=1&page=2
  83     @endverbatim
  84
  85     @subsection exampleresponse Example response
  86
  87     @verbatim
  88     <?xml version="1.0"?>
  89     <statuses type="array">
  90       <status>
  91         <text>back from the !yul !drupal meet with Evolving Web folk, @anarcat, @webchick and others, and an interesting refresher on SQL indexing</text>
  92         <truncated>false</truncated>
  93         <created_at>Wed Mar 31 01:33:02 +0000 2010</created_at>
  94         <in_reply_to_status_id/>
  95         <source>&lt;a href="http://code.google.com/p/microblog-purple/"&gt;mbpidgin&lt;/a&gt;</source>
  96         <id>26674201</id>
  97         <in_reply_to_user_id/>
  98         <in_reply_to_screen_name/>
  99         <geo/>
 100         <favorited>false</favorited>
 101         <user>
 102           <id>246</id>
 103           <name>Mark</name>
 104           <screen_name>lambic</screen_name>
 105           <location>Montreal, Canada</location>
 106           <description>Geek</description>
 107           <profile_image_url>http://avatar.identi.ca/246-48-20080702141545.png</profile_image_url>
 108           <url>http://lambic.co.uk</url>
 109           <protected>false</protected>
 110           <followers_count>73</followers_count>
 111           <profile_background_color>#F0F2F5</profile_background_color>
 112           <profile_text_color/>
 113           <profile_link_color>#002E6E</profile_link_color>
 114           <profile_sidebar_fill_color>#CEE1E9</profile_sidebar_fill_color>
 115           <profile_sidebar_border_color/>
 116           <friends_count>58</friends_count>
 117           <created_at>Wed Jul 02 14:12:15 +0000 2008</created_at>
 118           <favourites_count>2</favourites_count>
 119           <utc_offset>-14400</utc_offset>
 120           <time_zone>US/Eastern</time_zone>
 121           <profile_background_image_url/>
 122           <profile_background_tile>false</profile_background_tile>
 123           <statuses_count>933</statuses_count>
 124           <following>false</following>
 125           <notifications>false</notifications>
 126         </user>
 127       </status>
 128     </statuses>
 129     @endverbatim
 130 */
 131
 132 if (!defined('STATUSNET')) {
 133     exit(1);
 134 }
 135
 136 require_once INSTALLDIR . '/lib/apibareauth.php';
 137
 138 /**
 139  * Returns the most recent notices (default 20) posted by the target user.
 140  * This is the equivalent of 'You and friends' page accessed via Web.
 141  *
 142  * @category API
 143  * @package  StatusNet
 144  * @author   Craig Andrews <candrews@integralblue.com>
 145  * @author   Evan Prodromou <evan@status.net>
 146  * @author   Jeffery To <jeffery.to@gmail.com>
 147  * @author   mac65 <mac65@mac65.com>
 148  * @author   Mike Cochrane <mikec@mikenz.geek.nz>
 149  * @author   Robin Millette <robin@millette.info>
 150  * @author   Zach Copley <zach@status.net>
 151  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
 152  * @link     http://status.net/
 153  */
 154 class ApiTimelineFriendsAction extends ApiBareAuthAction
 155 {
 156     var $notices  = null;
 157
 158     /**
 159      * Take arguments for running
 160      *
 161      * @param array $args $_REQUEST args
 162      *
 163      * @return boolean success flag
 164      *
 165      */
 166     function prepare($args)
 167     {
 168         parent::prepare($args);
 169         $this->user = $this->getTargetUser($this->arg('id'));
 170
 171         if (empty($this->user)) {
 172             // TRANS: Client error displayed when requesting dents of a user and friends for a user that does not exist.
 173             $this->clientError(_('No such user.'), 404, $this->format);
 174             return;
 175         }
 176
 177         $this->notices = $this->getNotices();
 178
 179         return true;
 180     }
 181
 182     /**
 183      * Handle the request
 184      *
 185      * Just show the notices
 186      *
 187      * @param array $args $_REQUEST data (unused)
 188      *
 189      * @return void
 190      */
 191     function handle($args)
 192     {
 193         parent::handle($args);
 194         $this->showTimeline();
 195     }
 196
 197     /**
 198      * Show the timeline of notices
 199      *
 200      * @return void
 201      */
 202     function showTimeline()
 203     {
 204         $profile    = $this->user->getProfile();
 205         $avatar     = $profile->getAvatar(AVATAR_PROFILE_SIZE);
 206         $sitename   = common_config('site', 'name');
 207         // TRANS: Title of API timeline for a user and friends.
 208         // TRANS: %s is a username.
 209         $title      = sprintf(_("%s and friends"), $this->user->nickname);
 210         $taguribase = TagURI::base();
 211         $id         = "tag:$taguribase:FriendsTimeline:" . $this->user->id;
 212
 213         $subtitle = sprintf(
 214             // TRANS: Message is used as a subtitle. %1$s is a user nickname, %2$s is a site name.
 215             _('Updates from %1$s and friends on %2$s!'),
 216             $this->user->nickname,
 217             $sitename
 218         );
 219
 220         $link = common_local_url(
 221             'all',
 222              array('nickname' => $this->user->nickname)
 223         );
 224
 225         $self = $this->getSelfUri();
 226
 227         $logo = (!empty($avatar))
 228             ? $avatar->displayUrl()
 229             : Avatar::defaultImage(AVATAR_PROFILE_SIZE);
 230
 231         switch($this->format) {
 232         case 'xml':
 233             $this->showXmlTimeline($this->notices);
 234             break;
 235         case 'rss':
 236
 237             $this->showRssTimeline(
 238                 $this->notices,
 239                 $title,
 240                 $link,
 241                 $subtitle,
 242                 null,
 243                 $logo,
 244                 $self
 245             );
 246             break;
 247         case 'atom':
 248             header('Content-Type: application/atom+xml; charset=utf-8');
 249
 250             $atom = new AtomNoticeFeed($this->auth_user);
 251
 252             $atom->setId($id);
 253             $atom->setTitle($title);
 254             $atom->setSubtitle($subtitle);
 255             $atom->setLogo($logo);
 256             $atom->setUpdated('now');
 257             $atom->addLink($link);
 258             $atom->setSelfLink($self);
 259
 260             $atom->addEntryFromNotices($this->notices);
 261
 262             $this->raw($atom->getString());
 263
 264             break;
 265         case 'json':
 266             $this->showJsonTimeline($this->notices);
 267             break;
 268         case 'as':
 269             header('Content-Type: application/json; charset=utf-8');
 270             $doc = new ActivityStreamJSONDocument($this->auth_user);
 271             $doc->setTitle($title);
 272             $doc->addLink($link,'alternate', 'text/html');
 273             $doc->addItemsFromNotices($this->notices);
 274             $this->raw($doc->asString());
 275             break;
 276         default:
 277             // TRANS: Client error displayed when coming across a non-supported API method.
 278             $this->clientError(_('API method not found.'), $code = 404);
 279             break;
 280         }
 281     }
 282
 283     /**
 284      * Get notices
 285      *
 286      * @return array notices
 287      */
 288     function getNotices()
 289     {
 290         $notices = array();
 291
 292         $stream = new InboxNoticeStream($this->user);
 293
 294         $notice = $stream->getNotices(($this->page-1) * $this->count,
 295                                       $this->count,
 296                                       $this->since_id,
 297                                       $this->max_id);
 298
 299         while ($notice->fetch()) {
 300             $notices[] = clone($notice);
 301         }
 302
 303         return $notices;
 304     }
 305
 306     /**
 307      * Is this action read only?
 308      *
 309      * @param array $args other arguments
 310      *
 311      * @return boolean true
 312      */
 313     function isReadOnly($args)
 314     {
 315         return true;
 316     }
 317
 318     /**
 319      * When was this feed last modified?
 320      *
 321      * @return string datestamp of the latest notice in the stream
 322      */
 323     function lastModified()
 324     {
 325         if (!empty($this->notices) && (count($this->notices) > 0)) {
 326             return strtotime($this->notices[0]->created);
 327         }
 328
 329         return null;
 330     }
 331
 332     /**
 333      * An entity tag for this stream
 334      *
 335      * Returns an Etag based on the action name, language, user ID, and
 336      * timestamps of the first and last notice in the timeline
 337      *
 338      * @return string etag
 339      */
 340     function etag()
 341     {
 342         if (!empty($this->notices) && (count($this->notices) > 0)) {
 343             $last = count($this->notices) - 1;
 344
 345             return '"' . implode(
 346                                  ':',
 347                                  array($this->arg('action'),
 348                                        common_user_cache_hash($this->auth_user),
 349                                        common_language(),
 350                                        $this->user->id,
 351                                        strtotime($this->notices[0]->created),
 352                                        strtotime($this->notices[$last]->created))
 353                                  )
 354               . '"';
 355         }
 356
 357         return null;
 358     }
 359 }