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    Jeff Hodsdon <jeff@digg.com>
17 * @author    Bill Shupp <hostmaster@shupp.org>
18 * @copyright 2007-2008 Jeff Hodsdon <jeff@digg.com>
19 * @license   http://www.opensource.org/licenses/bsd-license.php New BSD License
20 * @version   Release: 0.2.14
21 * @link      http://pear.php.net/package/Services_Facebook
22 */
23
24require_once 'Services/Facebook/Common.php';
25require_once 'Services/Facebook/Exception.php';
26require_once 'Validate.php';
27
28/**
29 * Facebook Application Interface
30 *
31 * <code>
32 * <?php
33 * require_once 'Services/Facebook.php';
34 * $api = new Services_Facebook();
35 * $app = $api->connect->('');
36 * ?>
37 * </code>
38 *
39 * @category Services
40 * @package  Services_Facebook
41 * @author   Jeff Hodsdon <jeff@digg.com>
42 * @license  http://www.opensource.org/licenses/bsd-license.php New BSD License
43 * @version  Release: 0.2.14
44 * @link     http://wiki.developers.facebook.com
45 */
46class Services_Facebook_Connect extends Services_Facebook_Common
47{
48
49    /**
50     * Construct
51     *
52     * Various tasks that should be ran before non-static methods
53     *
54     * @access public
55     * @return void
56     */
57    public function __construct()
58    {
59        parent::__construct();
60
61        if (!function_exists('json_encode')) {
62            throw new Services_Facebook_Exception('PHP Function ' .
63                'json_encode() is required for Services_Facebook_Connect ' .
64                ' methods.');
65        }
66    }
67
68    /**
69     * Unconnected Friends Count
70     *
71     * Get the amount of users friends that have not connected their account
72     * to your site.  NOTE: These are users that you have sent connect.registerUser
73     * information.
74     *
75     * @access public
76     * @return int Amount of users
77     */
78    public function getUnconnectedFriendsCount()
79    {
80        $result = $this->callMethod('connect.getUnconnectedFriendsCount', array(
81            'session_key' => $this->sessionKey
82        ));
83
84        return (int) $result;
85    }
86
87    /**
88     * Register Users
89     *
90     * The accounts array may hold up to 1,000 accounts. Each account should hold
91     * these array keys: (account_id and account_url are optional)
92     *
93     * <code>
94     *
95     * // Hash the emails
96     * $hash1 = Services_Facebook_Connect::hashEmail('joe@example.com');
97     * $hash2 = Services_Facebook_Connect::hashEmail('jeff@example.com');
98     *
99     * $accounts = array();
100     *
101     * $accounts[] = array(
102     *     'email_hash'  => $hash1,
103     *     'account_id'  => 12345678,
104     *     'account_url' => 'http://example.com/users?id=12345678'
105     * )
106     *
107     * $accounts[] = array(
108     *     'email_hash'  => $hash2,
109     * )
110     *
111     * $connect = Services_Facebook::factory('Connect');
112     * $result  = $connect->registerUsers($accounts);
113     * </code>
114     *
115     * @param array $accounts Information about accounts
116     *
117     * @access public
118     * @throws Services_Facebook_Exception If emash_hash is missing or
119     *         another field was passed in that is not supported.
120     * @return object SimpleXML object from callMethod()
121     */
122    public function registerUsers(array $accounts)
123    {
124        $fields = array(
125            'email_hash',
126            'account_id',
127            'account_url'
128        );
129
130        foreach ($accounts as $account) {
131            if (empty($account['email_hash'])) {
132                throw new Services_Facebook_Exception('email_hash is ' .
133                    'required in each account map passed to ' .
134                    'Services_Facebook_Connect::registerUsers()');
135            }
136
137            $keys = array_keys($account);
138            foreach ($keys as $key) {
139                if (!in_array($key, $fields)) {
140                    throw new Services_Facebook_Exception('Field ' . $key .
141                        ' is not supported.');
142                }
143            }
144        }
145
146        $result = $this->callMethod('connect.registerUsers', array(
147            'accounts' => json_encode($accounts)
148        ));
149
150        $hashes = array();
151        foreach ($result->connect_registerUsers_response_elt as $hash) {
152            $hashes[] = (string) $hash;
153        }
154
155        return $hashes;
156    }
157
158    /**
159     * unregisterUsers
160     *
161     * This method allows a site to unregister a connected account. You should
162     * call this method if the user deletes his account on your site.
163     *
164     *
165     * <code>
166     * $hashes = array();
167     * $hashes[] = Services_Facebook_Connect::hashEmail('joe@example.com');
168     * $hashes[] = Services_Facebook_Connect::hashEmail('jeff@example.com');
169     *
170     * $connect = new Services_Facebook::factory('Connect');
171     * $result  = $connect->unregisterUsers($hashes);
172     * </code>
173     *
174     * @param array $emailHashes An array of email_hashes to unregister
175     *
176     * @access public
177     * @throws Services_Facebook_Exception if json_decode() is not available
178     * @return object SimpleXML object from callMethod()
179     */
180    public function unregisterUsers(array $emailHashes)
181    {
182        $result = $this->callMethod('connect.unregisterUsers', array(
183            'email_hashes' => json_encode($emailHashes)
184        ));
185
186        return (intval((string) $result) == 1);
187    }
188
189    /**
190     * hashEmail
191     *
192     * @param string $email Email to hash
193     *
194     * @static
195     * @access public
196     * @return string Hashed email address
197     * @throws Services_Facebook_Exception
198     * @see    http://www.php.net/crc32
199     * @see    http://www.php.net/md5
200     */
201    static public function hashEmail($email)
202    {
203        if (!Validate::email($email)) {
204            throw new Services_Facebook_Exception('Invalid email address passed to'
205                . ' Services_Facebook_Connect::hashEmail()');
206        }
207
208        $email = strtolower(trim($email));
209        $crc32 = sprintf("%u", crc32($email));
210        $md5   = md5($email);
211
212        return $crc32 . '_' . $md5;
213    }
214
215    /**
216     * hashEmails
217     *
218     * @param array $emails Emails to hash
219     *
220     * @static
221     * @access public
222     * @return array  Hashed emails
223     */
224    static public function hashEmails(array $emails)
225    {
226        foreach ($emails as &$email) {
227            $email = self::hashEmail($email);
228        }
229
230        return $emails;
231    }
232}
233
234?>
235