1<?php
2
3/**
4 * PHP5 interface for Facebook's REST API
5 *
6 * PHP version 5.1.0+
7 *
8 * LICENSE: This source file is subject to the New BSD license that is
9 * available through the world-wide-web at the following URI:
10 * http://www.opensource.org/licenses/bsd-license.php. If you did not receive
11 * a copy of the New BSD License and are unable to obtain it through the web,
12 * please send a note to license@php.net so we can mail you a copy immediately.
13 *
14 * @category  Services
15 * @package   Services_Facebook
16 * @author    Joe Stump <joe@joestump.net>
17 * @copyright 2007-2008 Joe Stump <joe@joestump.net>
18 * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
19 * @version   Release: 0.2.14
20 * @link      http://pear.php.net/package/Services_Facebook
21 */
22
23require_once 'Services/Facebook/Common.php';
24require_once 'Validate.php';
25
26/**
27 * Facebook Notifications Interface
28 *
29 * @category Services
30 * @package  Services_Facebook
31 * @author   Joe Stump <joe@joestump.net>
32 * @license  http://www.opensource.org/licenses/bsd-license.php New BSD License
33 * @version  Release: 0.2.14
34 * @link     http://wiki.developers.facebook.com
35 */
36class Services_Facebook_Notifications extends Services_Facebook_Common
37{
38    /**
39     * App to user notification type
40     *
41     * @see self::send()
42     */
43    const TYPE_APP_TO_USER = 'app_to_user';
44
45    /**
46     * User to user notification type
47     *
48     * @see self::send()
49     */
50    const TYPE_USER_TO_USER = 'user_to_user';
51
52    /**
53     * Get notifications for current user
54     *
55     * Returns all of the outstanding notifications for the given user, which
56     * include messages, pokes, shares, friend requests, group invites, and
57     * event invites.
58     *
59     * @return      object      Instance of SimpleXmlElement
60     * @link        http://wiki.developers.facebook.com/index.php/Notifications.get
61     */
62    public function get()
63    {
64        $args = array(
65            'session_key' => $this->sessionKey
66        );
67
68        return $this->callMethod('notifications.get', $args);
69    }
70
71    /**
72     * Send a notification
73     *
74     * When you send a notification you can send it to an array of Facebook
75     * uids. The notification should be valid FBML. Optionally, you can pass
76     *
77     * Optionally, you can pass a type parameter. 'general' (default)
78     * notifications require an active user session, while 'announcement'
79     * does not.
80     *
81     * The result value can either be true or a string. The string is a valid
82     * URI that you should redirect the user to for confirmation.
83     *
84     * @param array  $to           Facebook uids to send note to
85     * @param string $notification FBML of notification
86     * @param string $type         Type of notification
87     *
88     * @return mixed Confirmation URI or true
89     * @see self::TYPE_GENERAL, self::TYPE_ANNOUNCEMENT
90     * @link http://wiki.developers.facebook.com/index.php/Notifications.send
91     */
92    public function send(array $to, $notification, $type = self::TYPE_USER_TO_USER)
93    {
94        $args = array(
95            'to_ids' => implode(',', $to),
96            'notification' => $notification
97        );
98
99        if ($type == self::TYPE_USER_TO_USER) {
100            $args['session_key'] = $this->sessionKey;
101            $args['type']        = $type;
102        } elseif ($type == self::TYPE_APP_TO_USER) {
103            $args['type'] = $type;
104        } elseif ($type == 'announcement' || $type == 'general') {
105            // Backwards compatiblity
106            if ($type == 'general') {
107                $args['session_key'] = $this->sessionKey;
108            }
109            $args['type'] = $type;
110        } else {
111            // Backwards compatiblity
112            $args['email'] = $type;
113        }
114
115        $result = $this->callMethod('notifications.send', $args);
116        $check  = (string)$result;
117        if (strlen($check) && Validate::uri($check)) {
118            return $check;
119        }
120
121        return true;
122    }
123
124    /**
125     * Send an email out to application users
126     *
127     * @param array  $recipients An array of Facebook uids to send too
128     * @param string $subject    Subject of the email
129     * @param mixed  $text       Text or FBML and text for the body of the email
130     *
131     * @return array An array of success uids the email went out too
132     * @author Jeff Hodsdon <jeffhodsdon@gmail.com>
133     * @link http://wiki.developers.facebook.com/index.php/Notifications.sendEmail
134     */
135    public function sendEmail(array $recipients, $subject, $text = null)
136    {
137        $args = array(
138            'recipients' => implode(',', $recipients),
139            'subject' => $subject,
140            );
141
142        if (preg_match('/<fbml/i', $text)) {
143            $args['fbml'] = $text;
144        } else {
145            $args['text'] = $text;
146        }
147
148        $result = $this->callMethod('notifications.sendEmail', $args);
149        return explode(',', (string)$result);
150    }
151}
152
153?>
154