1: <?php
2: /**
3: * Photos methods for Horde_Service_Facebook
4: *
5: * Copyright 2009-2012 Horde LLC (http://www.horde.org/)
6: *
7: * @author Michael J. Rubinsky <mrubinsk@horde.org>
8: * @category Horde
9: * @package Service_Facebook
10: */
11: class Horde_Service_Facebook_Photos extends Horde_Service_Facebook_Base
12: {
13: /**
14: * Adds a tag with the given information to a photo. See the wiki for details:
15: *
16: * http://wiki.developers.facebook.com/index.php/Photos.addTag
17: *
18: * @param integer $pid The ID of the photo to be tagged
19: * @param integer $tag_uid The ID of the user being tagged. You must specify
20: * either the $tag_uid or the $tag_text parameter
21: * (unless $tags is specified).
22: * @param string $tag_text Some text identifying the person being tagged.
23: * You must specify either the $tag_uid or $tag_text
24: * parameter (unless $tags is specified).
25: * @param float $x The horizontal position of the tag, as a
26: * percentage from 0 to 100, from the left of the
27: * photo.
28: * @param float $y The vertical position of the tag, as a percentage
29: * from 0 to 100, from the top of the photo.
30: * @param array $tags (Optional) An array of maps, where each map
31: * can contain the tag_uid, tag_text, x, and y
32: * parameters defined above. If specified, the
33: * individual arguments are ignored.
34: * @param integer $owner_uid (Optional) The user ID of the user whose photo
35: * you are tagging. If this parameter is not
36: * specified, then it defaults to the session user.
37: *
38: * @return boolean
39: */
40: public function &addTag($pid, $tag_uid, $tag_text, $x, $y, array $tags, $uid = 0)
41: {
42: // Requires either a owner_uid or a session_key
43: if (empty($uid) && !$this->_facebook->auth->getSessionKey()) {
44: throw new Horde_Service_Facebook_Exception(
45: 'photos.addTag requires either a uid or a session_key',
46: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
47: }
48:
49: $params = array(
50: 'pid' => $pid,
51: 'tag_uid' => $tag_uid,
52: 'tag_text' => $tag_text,
53: 'x' => $x,
54: 'y' => $y,
55: 'tags' => (is_array($tags)) ? json_encode($tags) : null);
56:
57: if (!empty($owner_uid)) {
58: $params['owner_uid'] = $uid;
59: }
60: $results = $this->_facebook->callMethod('facebook.photos.addTag', $params);
61:
62: return $results;
63:
64: }
65:
66: /**
67: * Creates and returns a new album owned by the specified user or the current
68: * session user.
69: *
70: * @param string $name The name of the album.
71: * @param string $description (Optional) A description of the album.
72: * @param string $location (Optional) A description of the location.
73: * @param string $visible (Optional) A privacy setting for the album.
74: * One of 'friends', 'friends-of-friends',
75: * 'networks', or 'everyone'. Default 'everyone'.
76: * @param integer $uid (Optional) User id for creating the album; if
77: * not specified, the session user is used.
78: *
79: * @return array An album object
80: */
81: public function &createAlbum($name, $description = '', $location = '',
82: $visible = '', $uid = 0)
83: {
84: // Requires either a owner_uid or a session_key
85: if (empty($owner_uid) && !$this->_facebook->auth->getSessionKey()) {
86: throw new Horde_Service_Facebook_Exception(
87: 'photos.addTag requires either a owner_uid or a session_key',
88: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
89: }
90:
91: $params = array(
92: 'name' => $name,
93: 'description' => $description,
94: 'location' => $location,
95: 'visible' => $visible);
96:
97: // Yes, this method uses 'uid' while some of the others use
98: // 'owner_uid' - don't ask me...
99: if (!empty($uid)) {
100: $params['uid'] = $uid;
101: }
102: $results = $this->_facebook->callMethod(
103: 'facebook.photos.createAlbum', $params);
104:
105: return $results;
106: }
107:
108: /**
109: * Returns photos according to the filters specified.
110: *
111: * Note that at least one of these parameters needs to be specified, or an
112: * error is returned.
113: *
114: * @param integer $subj_id (Optional) Filter by uid of user tagged in the photos.
115: * @param integer $aid (Optional) Filter by an album, as returned by
116: * photos_getAlbums.
117: * @param string $pids (Optional) Restrict to a comma-separated list of pids
118: *
119: * @return array An array of photo objects.
120: */
121: public function &get($subj_id = null, $aid = null, $pids = null)
122: {
123: // Requires a session_key
124: if (!$skey = $this->_facebook->auth->getSessionKey()) {
125: throw new Horde_Service_Facebook_Exception(
126: 'photos.addTag requires a session_key',
127: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
128: }
129:
130: $params = array();
131: if ($subj_id) {
132: $params['subj_id'] = $subj_id;
133: }
134: if ($aid) {
135: $params['aid'] = $aid;
136: }
137: if ($pids) {
138: $params['pids'] = $pids;
139: }
140: $results = $this->_facebook->callMethod('facebook.photos.get', $params);
141:
142: return $results;
143: }
144:
145: /**
146: * Returns the albums created by the given user.
147: *
148: * Note that at least one of the (uid, aids) parameters must be specified.
149: *
150: * @param integer $uid (Optional) The uid of the user whose albums you want.
151: * A null will return the albums of the session user.
152: * @param string $aids (Optional) A comma-separated list of aids to restricti
153: * the query.
154: *
155: * @return array of album objects.
156: */
157: public function &getAlbums($uid = null, $aids = null)
158: {
159: // Requires a session_key
160: if (!$skey = $this->_facebook->auth->getSessionKey()) {
161: throw new Horde_Service_Facebook_Exception(
162: 'photos.addTag requires a session_key',
163: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
164: }
165:
166: $results = $this->_facebook->callMethod(
167: 'facebook.photos.getAlbums',
168: array('uid' => $uid,
169: 'aids' => $aids));
170:
171: return $results;
172: }
173:
174: /**
175: * Returns the tags on all photos specified.
176: *
177: * @param string $pids A list of pids to query
178: *
179: * @return array An array of photo tag objects, which include pid,
180: * subject uid, and two floating-point numbers (xcoord, ycoord)
181: * for tag pixel location.
182: */
183: public function &getTags($pids)
184: {
185: // Requires a session_key
186: if (!$skey = $this->_facebook->auth->getSessionKey()) {
187: throw new Horde_Service_Facebook_Exception(
188: 'photos.addTag requires a session_key',
189: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
190: }
191: $results = $this->_facebook->callMethod(
192: 'facebook.photos.getTags',
193: array('pids' => $pids));
194:
195: return $results;
196: }
197:
198: /**
199: * Uploads a photo.
200: *
201: * @param string $file The location of the photo on the local filesystem.
202: * @param integer $aid (Optional) The album into which to upload the
203: * photo.
204: * @param string $caption (Optional) A caption for the photo.
205: * @param integer $uid (Optional) The user ID of the user whose photo you
206: * are uploading
207: *
208: * @return array An array of user objects
209: */
210: public function upload($file, $aid = null, $caption = null, $uid = null)
211: {
212: // Requires either a owner_uid or a session_key
213: if (empty($uid) && !$skey = $this->_facebook->auth->getSessionKey()) {
214: throw new Horde_Service_Facebook_Exception(
215: 'photos.addTag requires either a uid or a session_key',
216: Horde_Service_Facebook_ErrorCodes::API_EC_SESSION_REQUIRED);
217: }
218:
219: $params = array('aid' => $aid, 'caption' => $caption);
220: if (!empty($uid)) {
221: $params['uid'] = $uid;
222: }
223: $results = $this->_facebook->callUploadMethod(
224: 'facebook.photos.upload', $params, $file);
225:
226: return $results;
227: }
228:
229: }