inc/subscription.php

   1 <?php
   2 /**
   3  * Utilities for handling (email) subscriptions
   4  *
   5  * The public interface of this file consists of the functions
   6  * - subscription_find
   7  * - subscription_send_digest
   8  * - subscription_send_list
   9  * - subscription_set
  10  * - get_info_subscribed
  11  * - subscription_addresslist
  12  *
  13  * @author  Adrian Lang <lang@cosmocode.de>
  14  * @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
  15  */
  16
  17 require_once DOKU_INC.'/inc/pageutils.php';
  18
  19 /**
  20  * Get the name of the metafile tracking subscriptions to target page or
  21  * namespace
  22  *
  23  * @param string $id The target page or namespace, specified by id; Namespaces
  24  *                   are identified by appending a colon.
  25  *
  26  * @author Adrian Lang <lang@cosmocode.de>
  27  */
  28 function subscription_filename($id) {
  29     $meta_fname = '.mlist';
  30     if ((substr($id, -1, 1) === ':')) {
  31         $meta_froot = getNS($id);
  32         if ($meta_froot === false) {
  33             $meta_fname = '/' . $meta_fname;
  34         }
  35     } else {
  36         $meta_froot = $id;
  37     }
  38     return metaFN($meta_froot, $meta_fname);
  39 }
  40
  41 /**
  42  * Set subscription information
  43  *
  44  * Allows to set subscription informations for permanent storage in meta files.
  45  * Subscriptions consist of a target object, a subscribing user, a subscribe
  46  * style and optional data.
  47  * A subscription may be deleted by specifying an empty subscribe style.
  48  * Only one subscription per target and user is allowed.
  49  * The function returns false on error, otherwise true. Note that no error is
  50  * returned if a subscription should be deleted but the user is not subscribed
  51  * and the subscription meta file exists.
  52  *
  53  * @param string $user      The subscriber or unsubscriber
  54  * @param string $page      The target object (page or namespace), specified by
  55  *                          id; Namespaces are identified by a trailing colon.
  56  * @param string $style     The subscribe style; DokuWiki currently implements
  57  *                          “every”, “digest”, and “list”.
  58  * @param string $data      An optional data blob
  59  * @param bool   $overwrite Whether an existing subscription may be overwritten
  60  *
  61  * @author Adrian Lang <lang@cosmocode.de>
  62  */
  63 function subscription_set($user, $page, $style, $data = null,
  64                           $overwrite = false) {
  65     global $lang;
  66     if (is_null($style)) {
  67         // Delete subscription.
  68         $file = subscription_filename($page);
  69         if (!@file_exists($file)) {
  70             msg(sprintf($lang['subscr_not_subscribed'], $user,
  71                         prettyprint_id($page)), -1);
  72             return false;
  73         }
  74
  75         // io_deleteFromFile does not return false if no line matched.
  76         return io_deleteFromFile($file,
  77                                  subscription_regex(array('user' => $user)),
  78                                  true);
  79     }
  80
  81     // Delete subscription if one exists and $overwrite is true. If $overwrite
  82     // is false, fail.
  83     $subs = subscription_find($page, array('user' => $user));
  84     if (count($subs) > 0 && array_pop(array_keys($subs)) === $page) {
  85         if (!$overwrite) {
  86             msg(sprintf($lang['subscr_already_subscribed'], $user,
  87                         prettyprint_id($page)), -1);
  88             return false;
  89         }
  90         // Fail if deletion failed, else continue.
  91         if (!subscription_set($user, $page, null)) {
  92             return false;
  93         }
  94     }
  95
  96     $file = subscription_filename($page);
  97     $content = auth_nameencode($user) . ' ' . $style;
  98     if (!is_null($data)) {
  99         $content .= ' ' . $data;
 100     }
 101     return io_saveFile($file, $content . "\n", true);
 102 }
 103
 104 /**
 105  * Recursively search for matching subscriptions
 106  *
 107  * This function searches all relevant subscription files for a page or
 108  * namespace.
 109  *
 110  * @param string $page The target object’s (namespace or page) id
 111  * @param array  $pre  A hash of predefined values
 112  *
 113  * @see function subscription_regex for $pre documentation
 114  *
 115  * @author Adrian Lang <lang@cosmocode.de>
 116  */
 117 function subscription_find($page, $pre) {
 118     // Construct list of files which may contain relevant subscriptions.
 119     $filenames = array(':' => subscription_filename(':'));
 120     do {
 121         $filenames[$page] = subscription_filename($page);
 122         $page = getNS(rtrim($page, ':')) . ':';
 123     } while ($page !== ':');
 124
 125     // Handle files.
 126     $matches = array();
 127     foreach ($filenames as $cur_page => $filename) {
 128         if (!@file_exists($filename)) {
 129             continue;
 130         }
 131         $subscriptions = file($filename);
 132         foreach ($subscriptions as $subscription) {
 133             if (strpos($subscription, ' ') === false) {
 134                 // This is an old subscription file.
 135                 $subscription = trim($subscription) . " every\n";
 136             }
 137             if (preg_match(subscription_regex($pre), $subscription,
 138                            $line_matches) === 0) {
 139                 continue;
 140             }
 141             $match = array_slice($line_matches, 1);
 142             if (!isset($matches[$cur_page])) {
 143                 $matches[$cur_page] = array();
 144             }
 145             $matches[$cur_page][] = $match;
 146         }
 147     }
 148     return array_reverse($matches);
 149 }
 150
 151 /**
 152  * Get data for $INFO['subscribed']
 153  *
 154  * $INFO['subscribed'] is either false if no subscription for the current page
 155  * and user is in effect. Else it contains an array of arrays with the fields
 156  * “target”, “style”, and optionally “data”.
 157  *
 158  * @author Adrian Lang <lang@cosmocode.de>
 159  */
 160 function get_info_subscribed() {
 161     global $ID;
 162     global $conf;
 163     if (!$conf['subscribers']) {
 164         return false;
 165     }
 166
 167     $subs = subscription_find($ID, array('user' => $_SERVER['REMOTE_USER']));
 168     if (count($subs) === 0) {
 169         return false;
 170     }
 171
 172     $_ret = array();
 173     foreach ($subs as $target => $subs_data) {
 174         $new = array('target' => $target,
 175                      'style'  => $subs_data[0][0]);
 176         if (count($subs_data[0]) > 1) {
 177             $new['data'] = $subs_data[0][1];
 178         }
 179         $_ret[] = $new;
 180     }
 181
 182     return $_ret;
 183 }
 184
 185 /**
 186  * Construct a regular expression parsing a subscription definition line
 187  *
 188  * @param array $pre A hash of predefined values; “user”, “style”, and
 189  *                   “data” may be set to limit the results to
 190  *                   subscriptions matching these parameters. If
 191  *                   “escaped” is true, these fields are inserted into the
 192  *                   regular expression without escaping.
 193  *
 194  * @author Adrian Lang <lang@cosmocode.de>
 195  */
 196 function subscription_regex($pre = array()) {
 197     if (!isset($pre['escaped']) || $pre['escaped'] === false) {
 198         $pre = array_map('preg_quote_cb', $pre);
 199     }
 200     foreach (array('user', 'style', 'data') as $key) {
 201         if (!isset($pre[$key])) {
 202             $pre[$key] = '(\S+)';
 203         }
 204     }
 205     return '/^' . $pre['user'] . '(?: ' . $pre['style'] .
 206            '(?: ' . $pre['data'] . ')?)?$/';
 207 }
 208
 209 /**
 210  * Return a string with the email addresses of all the
 211  * users subscribed to a page
 212  *
 213  * This is the default action for COMMON_NOTIFY_ADDRESSLIST.
 214  *
 215  * @param array $data Containing $id (the page id), $self (whether the author
 216  *                    should be notified, $addresslist (current email address
 217  *                    list)
 218  *
 219  * @author Steven Danz <steven-danz@kc.rr.com>
 220  * @author Adrian Lang <lang@cosmocode.de>
 221  */
 222 function subscription_addresslist(&$data){
 223     global $conf;
 224     global $auth;
 225
 226     $id = $data['id'];
 227     $self = $data['self'];
 228     $addresslist = $data['addresslist'];
 229
 230     if (!$conf['subscribers']) {
 231         return '';
 232     }
 233     $pres = array('style' => 'every', 'escaped' => true);
 234     if (!$self && isset($_SERVER['REMOTE_USER'])) {
 235         $pres['user'] = '((?:(?!' . preg_quote_cb($_SERVER['REMOTE_USER']) .
 236                         ')\S?)+)';
 237     }
 238     $subs = subscription_find($id, $pres);
 239     $emails = array();
 240     foreach ($subs as $by_targets) {
 241         foreach ($by_targets as $sub) {
 242             $info = $auth->getUserData($sub[0]);
 243             if ($info === false) continue;
 244             $level = auth_aclcheck($id, $sub[0], $info['grps']);
 245             if ($level >= AUTH_READ) {
 246                 if (strcasecmp($info['mail'], $conf['notify']) != 0) {
 247                     $emails[$sub[0]] =  $info['mail'];
 248                 }
 249             }
 250         }
 251     }
 252     $data['addresslist'] = trim($addresslist . ',' . implode(',', $emails), ',');
 253 }
 254
 255 /**
 256  * Send a digest mail
 257  *
 258  * Sends a digest mail showing a bunch of changes.
 259  *
 260  * @param string $subscriber_mail The target mail address
 261  * @param array  $change          The newest change
 262  * @param int    $lastupdate      Time of the last notification
 263  *
 264  * @author Adrian Lang <lang@cosmocode.de>
 265  */
 266 function subscription_send_digest($subscriber_mail, $change, $lastupdate) {
 267     $id = $change['id'];
 268     $n = 0;
 269     do {
 270         $rev = getRevisions($id, $n++, 1);
 271         $rev = (count($rev) > 0) ? $rev[0] : null;
 272     } while (!is_null($rev) && $rev > $lastupdate);
 273
 274     $ip = $change['ip'];
 275     $replaces = array('NEWPAGE'   => wl($id, '', true, '&'),
 276                       'SUBSCRIBE' => wl($id, array('do' => 'subscribe'), true, '&'));
 277     if (!is_null($rev)) {
 278         $subject = 'changed';
 279         $replaces['OLDPAGE'] = wl($id, "rev=$rev", true, '&');
 280         require_once DOKU_INC.'inc/DifferenceEngine.php';
 281         $df = new Diff(explode("\n", rawWiki($id, $rev)),
 282                         explode("\n", rawWiki($id)));
 283         $dformat = new UnifiedDiffFormatter();
 284         $replaces['DIFF'] = $dformat->format($df);
 285     } else {
 286         $subject = 'newpage';
 287         $replaces['OLDPAGE'] = 'none';
 288         $replaces['DIFF'] = rawWiki($id);
 289     }
 290     subscription_send($subscriber_mail, $replaces, $subject, $id,
 291                       'subscr_digest');
 292 }
 293
 294 /**
 295  * Send a list mail
 296  *
 297  * Sends a list mail showing a list of changed pages.
 298  *
 299  * @param string $subscriber_mail The target mail address
 300  * @param array  $changes         Array of changes
 301  * @param string $id              The id of the namespace
 302  *
 303  * @author Adrian Lang <lang@cosmocode.de>
 304  */
 305 function subscription_send_list($subscriber_mail, $changes, $id) {
 306     $list = '';
 307     foreach ($changes as $change) {
 308         $list .= '* ' . $change['id'] . NL;
 309     }
 310     subscription_send($subscriber_mail,
 311                       array('DIFF'      => rtrim($list),
 312                             'SUBSCRIBE' => wl($changes[0]['id'],
 313                                               array('do' => 'subscribe'),
 314                                               true, '&')),
 315                       'subscribe_list',
 316                       prettyprint_id($id),
 317                       'subscr_list');
 318 }
 319
 320 /**
 321  * Helper function for sending a mail
 322  *
 323  * @param string $subscriber_mail The target mail address
 324  * @param array  $replaces        Predefined parameters used to parse the
 325  *                                template
 326  * @param string $subject         The lang id of the mail subject (without the
 327  *                                prefix “mail_”)
 328  * @param string $id              The page or namespace id
 329  * @param string $template        The name of the mail template
 330  *
 331  * @author Adrian Lang <lang@cosmocode.de>
 332  */
 333 function subscription_send($subscriber_mail, $replaces, $subject, $id, $template) {
 334     global $conf;
 335
 336     $text = rawLocale($template);
 337     $replaces = array_merge($replaces, array('TITLE'       => $conf['title'],
 338                                              'DOKUWIKIURL' => DOKU_URL,
 339                                              'PAGE'        => $id));
 340
 341     foreach ($replaces as $key => $substitution) {
 342         $text = str_replace('@'.strtoupper($key).'@', $substitution, $text);
 343     }
 344
 345     global $lang;
 346     $subject = $lang['mail_' . $subject] . ' ' . $id;
 347     mail_send('', '['.$conf['title'].'] '. $subject, $text,
 348               $conf['mailfrom'], '', $subscriber_mail);
 349 }