]> git.mxchange.org Git - quix0rs-gnu-social.git/blob - lib/microappplugin.php
Merge remote-tracking branch 'origin/1.0.x' into 1.0.x
[quix0rs-gnu-social.git] / lib / microappplugin.php
1 <?php
2 /**
3  * StatusNet - the distributed open-source microblogging tool
4  * Copyright (C) 2011, StatusNet, Inc.
5  *
6  * Superclass for microapp plugin
7  *
8  * PHP version 5
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU Affero General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Affero General Public License for more details.
19  *
20  * You should have received a copy of the GNU Affero General Public License
21  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
22  *
23  * @category  Microapp
24  * @package   StatusNet
25  * @author    Evan Prodromou <evan@status.net>
26  * @copyright 2011 StatusNet, Inc.
27  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
28  * @link      http://status.net/
29  */
30
31 if (!defined('STATUSNET')) {
32     // This check helps protect against security problems;
33     // your code file can't be executed directly from the web.
34     exit(1);
35 }
36
37 /**
38  * Superclass for microapp plugins
39  *
40  * This class lets you define micro-applications with different kinds of activities.
41  *
42  * The applications work more-or-less like other
43  *
44  * @category  Microapp
45  * @package   StatusNet
46  * @author    Evan Prodromou <evan@status.net>
47  * @copyright 2011 StatusNet, Inc.
48  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
49  * @link      http://status.net/
50  */
51 abstract class MicroAppPlugin extends Plugin
52 {
53     /**
54      * Returns a localized string which represents this micro-app,
55      * to be shown to users selecting what type of post to make.
56      * This is paired with the key string in $this->tag().
57      *
58      * All micro-app classes must override this method.
59      *
60      * @return string
61      */
62     abstract function appTitle();
63
64     /**
65      * Returns a key string which represents this micro-app in HTML
66      * ids etc, as when offering selection of what type of post to make.
67      * This is paired with the user-visible localizable $this->appTitle().
68      *
69      * All micro-app classes must override this method.
70      */
71     abstract function tag();
72
73     /**
74      * Return a list of ActivityStreams object type URIs
75      * which this micro-app handles. Default implementations
76      * of the base class will use this list to check if a
77      * given ActivityStreams object belongs to us, via
78      * $this->isMyNotice() or $this->isMyActivity.
79      *
80      * All micro-app classes must override this method.
81      *
82      * @fixme can we confirm that these types are the same
83      * for Atom and JSON streams? Any limitations or issues?
84      *
85      * @return array of strings
86      */
87     abstract function types();
88
89     /**
90      * Given a parsed ActivityStreams activity, your plugin
91      * gets to figure out how to actually save it into a notice
92      * and any additional data structures you require.
93      *
94      * This will handle things received via AtomPub, OStatus
95      * (PuSH and Salmon transports), or ActivityStreams-based
96      * backup/restore of account data.
97      *
98      * You should be able to accept as input the output from your
99      * $this->activityObjectFromNotice(). Where applicable, try to
100      * use existing ActivityStreams structures and object types,
101      * and be liberal in accepting input from what might be other
102      * compatible apps.
103      *
104      * All micro-app classes must override this method.
105      *
106      * @fixme are there any standard options?
107      *
108      * @param Activity $activity
109      * @param Profile $actor
110      * @param array $options=array()
111      *
112      * @return Notice the resulting notice
113      */
114     abstract function saveNoticeFromActivity($activity, $actor, $options=array());
115
116     /**
117      * Given an existing Notice object, your plugin gets to
118      * figure out how to arrange it into an ActivityStreams
119      * object.
120      *
121      * This will be how your specialized notice gets output in
122      * Atom feeds and JSON-based ActivityStreams output, including
123      * account backup/restore and OStatus (PuSH and Salmon transports).
124      *
125      * You should be able to round-trip data from this format back
126      * through $this->saveNoticeFromActivity(). Where applicable, try
127      * to use existing ActivityStreams structures and object types,
128      * and consider interop with other compatible apps.
129      *
130      * All micro-app classes must override this method.
131      *
132      * @fixme this outputs an ActivityObject, not an Activity. Any compat issues?
133      *
134      * @param Notice $notice
135      *
136      * @return ActivityObject
137      */
138     abstract function activityObjectFromNotice($notice);
139
140     /**
141      * When building the primary notice form, we'll fetch also some
142      * alternate forms for specialized types -- that's you!
143      *
144      * Return a custom Widget or Form object for the given output
145      * object, and it'll be included in the HTML output. Beware that
146      * your form may be initially hidden.
147      *
148      * All micro-app classes must override this method.
149      *
150      * @param HTMLOutputter $out
151      * @return Widget
152      */
153     abstract function entryForm($out);
154
155     /**
156      * When a notice is deleted, you'll be called here for a chance
157      * to clean up any related resources.
158      *
159      * All micro-app classes must override this method.
160      *
161      * @param Notice $notice
162      */
163     abstract function deleteRelated($notice);
164
165     /**
166      * Check if a given notice object should be handled by this micro-app
167      * plugin.
168      *
169      * The default implementation checks against the activity type list
170      * returned by $this->types(). You can override this method to expand
171      * your checks.
172      *
173      * @param Notice $notice
174      * @return boolean
175      */
176     function isMyNotice($notice) {
177         $types = $this->types();
178         return ($notice->verb == ActivityVerb::POST) && in_array($notice->object_type, $types);
179     }
180
181     /**
182      * Check if a given ActivityStreams activity should be handled by this
183      * micro-app plugin.
184      *
185      * The default implementation checks against the activity type list
186      * returned by $this->types(), and requires that exactly one matching
187      * object be present. You can override this method to expand
188      * your checks or to compare the activity's verb, etc.
189      *
190      * @param Activity $activity
191      * @return boolean
192      */
193     function isMyActivity($activity) {
194         $types = $this->types();
195         return (count($activity->objects) == 1 &&
196                 ($activity->objects[0] instanceof ActivityObject) &&
197                 ($activity->verb == ActivityVerb::POST) &&
198                 in_array($activity->objects[0]->type, $types));
199     }
200
201     /**
202      * Called when generating Atom XML ActivityStreams output from an
203      * ActivityObject belonging to this plugin. Gives the plugin
204      * a chance to add custom output.
205      *
206      * Note that you can only add output of additional XML elements,
207      * not change existing stuff here.
208      *
209      * If output is already handled by the base Activity classes,
210      * you can leave this base implementation as a no-op.
211      *
212      * @param ActivityObject $obj
213      * @param XMLOutputter $out to add elements at end of object
214      */
215     function activityObjectOutputAtom(ActivityObject $obj, XMLOutputter $out)
216     {
217         // default is a no-op
218     }
219
220     /**
221      * Called when generating JSON ActivityStreams output from an
222      * ActivityObject belonging to this plugin. Gives the plugin
223      * a chance to add custom output.
224      *
225      * Modify the array contents to your heart's content, and it'll
226      * all get serialized out as JSON.
227      *
228      * If output is already handled by the base Activity classes,
229      * you can leave this base implementation as a no-op.
230      *
231      * @param ActivityObject $obj
232      * @param array &$out JSON-targeted array which can be modified
233      */
234     public function activityObjectOutputJson(ActivityObject $obj, array &$out)
235     {
236         // default is a no-op
237     }
238
239     /**
240      * When a notice is deleted, delete the related objects
241      * by calling the overridable $this->deleteRelated().
242      *
243      * @param Notice $notice Notice being deleted
244      *
245      * @return boolean hook value
246      */
247     function onNoticeDeleteRelated($notice)
248     {
249         if ($this->isMyNotice($notice)) {
250             $this->deleteRelated($notice);
251         }
252
253         return true;
254     }
255
256     /**
257      * Output the HTML for this kind of object in a list
258      *
259      * @param NoticeListItem $nli The list item being shown.
260      *
261      * @return boolean hook value
262      *
263      * @fixme WARNING WARNING WARNING this closes a 'div' that is implicitly opened in BookmarkPlugin's showNotice implementation
264      */
265     function onStartShowNoticeItem($nli)
266     {
267         if (!$this->isMyNotice($nli->notice)) {
268             return true;
269         }
270
271         $adapter = $this->adaptNoticeListItem($nli);
272
273         if (!empty($adapter)) {
274             $adapter->showNotice();
275             $adapter->showNoticeAttachments();
276             $adapter->showNoticeInfo();
277             $adapter->showNoticeOptions();
278         } else {
279             $this->oldShowNotice($nli);
280         }
281
282         return false;
283     }
284
285     /**
286      * Given a notice list item, returns an adapter specific
287      * to this plugin.
288      *
289      * @param NoticeListItem $nli item to adapt
290      *
291      * @return NoticeListItemAdapter adapter or null
292      */
293     function adaptNoticeListItem($nli)
294     {
295       return null;
296     }
297
298     function oldShowNotice($nli)
299     {
300         $out = $nli->out;
301         $notice = $nli->notice;
302
303         try {
304             $this->showNotice($notice, $out);
305         } catch (Exception $e) {
306             common_log(LOG_ERR, $e->getMessage());
307             // try to fall back
308             $out->elementStart('div');
309             $nli->showAuthor();
310             $nli->showContent();
311         }
312
313         $nli->showNoticeLink();
314         $nli->showNoticeSource();
315         $nli->showNoticeLocation();
316         $nli->showContext();
317         $nli->showRepeat();
318
319         $out->elementEnd('div');
320
321         $nli->showNoticeOptions();
322     }
323
324     /**
325      * Render a notice as one of our objects
326      *
327      * @param Notice         $notice  Notice to render
328      * @param ActivityObject &$object Empty object to fill
329      *
330      * @return boolean hook value
331      */
332     function onStartActivityObjectFromNotice($notice, &$object)
333     {
334         if ($this->isMyNotice($notice)) {
335             $object = $this->activityObjectFromNotice($notice);
336             return false;
337         }
338
339         return true;
340     }
341
342     /**
343      * Handle a posted object from PuSH
344      *
345      * @param Activity        $activity activity to handle
346      * @param Ostatus_profile $oprofile Profile for the feed
347      *
348      * @return boolean hook value
349      */
350     function onStartHandleFeedEntryWithProfile($activity, $oprofile, &$notice)
351     {
352         if ($this->isMyActivity($activity)) {
353
354             $actor = $oprofile->checkAuthorship($activity);
355
356             if (empty($actor)) {
357                 // TRANS: Client exception thrown when no author for an activity was found.
358                 throw new ClientException(_('Cannot get author for activity.'));
359             }
360
361             $object = $activity->objects[0];
362
363             $options = array('uri' => $object->id,
364                              'url' => $object->link,
365                              'is_local' => Notice::REMOTE,
366                              'source' => 'ostatus');
367
368             // $actor is an ostatus_profile
369             $notice = $this->saveNoticeFromActivity($activity, $actor->localProfile(), $options);
370
371             return false;
372         }
373
374         return true;
375     }
376
377     /**
378      * Handle a posted object from Salmon
379      *
380      * @param Activity $activity activity to handle
381      * @param mixed    $target   user or group targeted
382      *
383      * @return boolean hook value
384      */
385
386     function onStartHandleSalmonTarget($activity, $target)
387     {
388         if ($this->isMyActivity($activity)) {
389             $this->log(LOG_INFO, "Checking {$activity->id} as a valid Salmon slap.");
390
391             if ($target instanceof User_group) {
392                 $uri = $target->getUri();
393                 if (!in_array($uri, $activity->context->attention)) {
394                     // @todo FIXME: please document (i18n).
395                     // TRANS: Client exception thrown when ...
396                     throw new ClientException(_('Bookmark not posted to this group.'));
397                 }
398             } else if ($target instanceof User) {
399                 $uri      = $target->uri;
400                 $original = null;
401                 if (!empty($activity->context->replyToID)) {
402                     $original = Notice::staticGet('uri',
403                                                   $activity->context->replyToID);
404                 }
405                 if (!in_array($uri, $activity->context->attention) &&
406                     (empty($original) ||
407                      $original->profile_id != $target->id)) {
408                     // @todo FIXME: Please document (i18n).
409                     // TRANS: Client exception when ...
410                     throw new ClientException(_('Object not posted to this user.'));
411                 }
412             } else {
413                 // TRANS: Server exception thrown when a micro app plugin uses a target that cannot be handled.
414                 throw new ServerException(_('Do not know how to handle this kind of target.'));
415             }
416
417             $actor = Ostatus_profile::ensureActivityObjectProfile($activity->actor);
418
419             $object = $activity->objects[0];
420
421             $options = array('uri' => $object->id,
422                              'url' => $object->link,
423                              'is_local' => Notice::REMOTE,
424                              'source' => 'ostatus');
425
426             // $actor is an ostatus_profile
427             $this->saveNoticeFromActivity($activity, $actor->localProfile(), $options);
428
429             return false;
430         }
431
432         return true;
433     }
434
435     /**
436      * Handle object posted via AtomPub
437      *
438      * @param Activity &$activity Activity that was posted
439      * @param User     $user      User that posted it
440      * @param Notice   &$notice   Resulting notice
441      *
442      * @return boolean hook value
443      */
444     function onStartAtomPubNewActivity(&$activity, $user, &$notice)
445     {
446         if ($this->isMyActivity($activity)) {
447
448             $options = array('source' => 'atompub');
449
450             // $user->getProfile() is a Profile
451             $notice = $this->saveNoticeFromActivity($activity,
452                                                     $user->getProfile(),
453                                                     $options);
454
455             return false;
456         }
457
458         return true;
459     }
460
461     /**
462      * Handle object imported from a backup file
463      *
464      * @param User           $user     User to import for
465      * @param ActivityObject $author   Original author per import file
466      * @param Activity       $activity Activity to import
467      * @param boolean        $trusted  Is this a trusted user?
468      * @param boolean        &$done    Is this done (success or unrecoverable error)
469      *
470      * @return boolean hook value
471      */
472     function onStartImportActivity($user, $author, $activity, $trusted, &$done)
473     {
474         if ($this->isMyActivity($activity)) {
475
476             $obj = $activity->objects[0];
477
478             $options = array('uri' => $object->id,
479                              'url' => $object->link,
480                              'source' => 'restore');
481
482             // $user->getProfile() is a Profile
483             $saved = $this->saveNoticeFromActivity($activity,
484                                                    $user->getProfile(),
485                                                    $options);
486
487             if (!empty($saved)) {
488                 $done = true;
489             }
490
491             return false;
492         }
493
494         return true;
495     }
496
497     /**
498      * Event handler gives the plugin a chance to add custom
499      * Atom XML ActivityStreams output from a previously filled-out
500      * ActivityObject.
501      *
502      * The atomOutput method is called if it's one of
503      * our matching types.
504      *
505      * @param ActivityObject $obj
506      * @param XMLOutputter $out to add elements at end of object
507      * @return boolean hook return value
508      */
509     function onEndActivityObjectOutputAtom(ActivityObject $obj, XMLOutputter $out)
510     {
511         if (in_array($obj->type, $this->types())) {
512             $this->activityObjectOutputAtom($obj, $out);
513         }
514         return true;
515     }
516
517     /**
518      * Event handler gives the plugin a chance to add custom
519      * JSON ActivityStreams output from a previously filled-out
520      * ActivityObject.
521      *
522      * The activityObjectOutputJson method is called if it's one of
523      * our matching types.
524      *
525      * @param ActivityObject $obj
526      * @param array &$out JSON-targeted array which can be modified
527      * @return boolean hook return value
528      */
529     function onEndActivityObjectOutputJson(ActivityObject $obj, array &$out)
530     {
531         if (in_array($obj->type, $this->types())) {
532             $this->activityObjectOutputJson($obj, $out);
533         }
534         return true;
535     }
536
537     function onStartShowEntryForms(&$tabs)
538     {
539         $tabs[$this->tag()] = $this->appTitle();
540         return true;
541     }
542
543     function onStartMakeEntryForm($tag, $out, &$form)
544     {
545         if ($tag == $this->tag()) {
546             $form = $this->entryForm($out);
547             return false;
548         }
549
550         return true;
551     }
552
553     function showNotice($notice, $out)
554     {
555         // TRANS: Server exception thrown when a micro app plugin developer has not done his job too well.
556         throw new ServerException(_('You must implement either adaptNoticeListItem() or showNotice().'));
557     }
558 }