/libraries/joomla/facebook/photo.php

  1<?php
  2/**
  3 * @package     Joomla.Platform
  4 * @subpackage  Facebook
  5 *
  6 * @copyright   Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
  7 * @license     GNU General Public License version 2 or later; see LICENSE
  8 */
  9
 10
 11defined('JPATH_PLATFORM') or die();
 12
 13
 14/**
 15 * Facebook API Photo class for the Joomla Platform.
 16 *
 17 * @see    http://developers.facebook.com/docs/reference/api/photo/
 18 * @since  13.1
 19 */
 20class JFacebookPhoto extends JFacebookObject
 21{
 22	/**
 23	 * Method to get a photo. Requires authentication and user_photos or friends_photos permission for private photos.
 24	 *
 25	 * @param   string  $photo  The photo id.
 26	 *
 27	 * @return  mixed   The decoded JSON response or false if the client is not authenticated.
 28	 *
 29	 * @since   13.1
 30	 */
 31	public function getPhoto($photo)
 32	{
 33		return $this->get($photo);
 34	}
 35
 36	/**
 37	 * Method to get a photo's comments. Requires authentication and user_photos or friends_photos permission for private photos.
 38	 *
 39	 * @param   string   $photo   The photo id.
 40	 * @param   integer  $limit   The number of objects per page.
 41	 * @param   integer  $offset  The object's number on the page.
 42	 * @param   string   $until   A unix timestamp or any date accepted by strtotime.
 43	 * @param   string   $since   A unix timestamp or any date accepted by strtotime.
 44	 *
 45	 * @return  mixed   The decoded JSON response or false if the client is not authenticated.
 46	 *
 47	 * @since   13.1
 48	 */
 49	public function getComments($photo, $limit = 0, $offset = 0, $until = null, $since = null)
 50	{
 51		return $this->getConnection($photo, 'comments', '', $limit, $offset, $until, $since);
 52	}
 53
 54	/**
 55	 * Method to comment on a photo. Requires authentication and publish_stream permission, user_photos or friends_photos permission for private photos.
 56	 *
 57	 * @param   string  $photo    The photo id.
 58	 * @param   string  $message  The comment's text.
 59	 *
 60	 * @return  mixed   The decoded JSON response or false if the client is not authenticated.
 61	 *
 62	 * @since   13.1
 63	 */
 64	public function createComment($photo, $message)
 65	{
 66		// Set POST request parameters.
 67		$data['message'] = $message;
 68
 69		return $this->createConnection($photo, 'comments', $data);
 70	}
 71
 72	/**
 73	 * Method to delete a comment. Requires authentication and publish_stream permission, user_photos or friends_photos permission for private photos.
 74	 *
 75	 * @param   string  $comment  The comment's id.
 76	 *
 77	 * @return  boolean Returns true if successful, and false otherwise.
 78	 *
 79	 * @since   13.1
 80	 */
 81	public function deleteComment($comment)
 82	{
 83		return $this->deleteConnection($comment);
 84	}
 85
 86	/**
 87	 * Method to get photo's likes. Requires authentication and user_photos or friends_photos permission for private photos.
 88	 *
 89	 * @param   string   $photo   The photo id.
 90	 * @param   integer  $limit   The number of objects per page.
 91	 * @param   integer  $offset  The object's number on the page.
 92	 * @param   string   $until   A unix timestamp or any date accepted by strtotime.
 93	 * @param   string   $since   A unix timestamp or any date accepted by strtotime.
 94	 *
 95	 * @return  mixed   The decoded JSON response or false if the client is not authenticated.
 96	 *
 97	 * @since   13.1
 98	 */
 99	public function getLikes($photo, $limit = 0, $offset = 0, $until = null, $since = null)
100	{
101		return $this->getConnection($photo, 'likes', '', $limit, $offset, $until, $since);
102	}
103
104	/**
105	 * Method to like a photo. Requires authentication and publish_stream permission, user_photos or friends_photos permission for private photos.
106	 *
107	 * @param   string  $photo  The photo id.
108	 *
109	 * @return  boolean Returns true if successful, and false otherwise.
110	 *
111	 * @since   13.1
112	 */
113	public function createLike($photo)
114	{
115		return $this->createConnection($photo, 'likes');
116	}
117
118	/**
119	 * Method to unlike a photo. Requires authentication and publish_stream permission, user_photos or friends_photos permission for private photos.
120	 *
121	 * @param   string  $photo  The photo id.
122	 *
123	 * @return  boolean Returns true if successful, and false otherwise.
124	 *
125	 * @since   13.1
126	 */
127	public function deleteLike($photo)
128	{
129		return $this->deleteConnection($photo, 'likes');
130	}
131
132	/**
133	 * Method to get the Users tagged in the photo. Requires authentication and user_photos or friends_photos permission for private photos.
134	 *
135	 * @param   string   $photo   The photo id.
136	 * @param   integer  $limit   The number of objects per page.
137	 * @param   integer  $offset  The object's number on the page.
138	 * @param   string   $until   A unix timestamp or any date accepted by strtotime.
139	 * @param   string   $since   A unix timestamp or any date accepted by strtotime.
140	 *
141	 * @return  mixed   The decoded JSON response or false if the client is not authenticated.
142	 *
143	 * @since   13.1
144	 */
145	public function getTags($photo, $limit = 0, $offset = 0, $until = null, $since = null)
146	{
147		return $this->getConnection($photo, 'tags', '', $limit, $offset, $until, $since);
148	}
149
150	/**
151	 * Method to tag one or more Users in a photo. $to or $tag_text required.
152	 * Requires authentication and publish_stream permission, user_photos permission for private photos.
153	 *
154	 * @param   string   $photo     The photo id.
155	 * @param   mixed    $to        ID of the User or an array of Users to tag in the photo: [{"id":"1234"}, {"id":"12345"}].
156	 * @param   string   $tag_text  A text string to tag.
157	 * @param   integer  $x         x coordinate of tag, as a percentage offset from the left edge of the picture.
158	 * @param   integer  $y         y coordinate of tag, as a percentage offset from the top edge of the picture.
159	 *
160	 * @return  boolean Returns true if successful, and false otherwise.
161	 *
162	 * @since   13.1
163	 */
164	public function createTag($photo, $to = null, $tag_text = null, $x = null, $y = null)
165	{
166		// Set POST request parameters.
167		if (is_array($to))
168		{
169			$data['tags'] = $to;
170		}
171		else
172		{
173			$data['to'] = $to;
174		}
175
176		if ($tag_text)
177		{
178			$data['tag_text'] = $tag_text;
179		}
180
181		if ($x)
182		{
183			$data['x'] = $x;
184		}
185
186		if ($y)
187		{
188			$data['y'] = $y;
189		}
190
191		return $this->createConnection($photo, 'tags', $data);
192	}
193
194	/**
195	 * Method to update the position of the tag for a particular Users in a photo.
196	 * Requires authentication and publish_stream permission, user_photos permission for private photos.
197	 *
198	 * @param   string   $photo  The photo id.
199	 * @param   string   $to     ID of the User to update tag in the photo.
200	 * @param   integer  $x      x coordinate of tag, as a percentage offset from the left edge of the picture.
201	 * @param   integer  $y      y coordinate of tag, as a percentage offset from the top edge of the picture.
202	 *
203	 * @return  boolean Returns true if successful, and false otherwise.
204	 *
205	 * @since   13.1
206	 */
207	public function updateTag($photo, $to, $x = null, $y = null)
208	{
209		// Set POST request parameters.
210		$data['to'] = $to;
211
212		if ($x)
213		{
214			$data['x'] = $x;
215		}
216
217		if ($y)
218		{
219			$data['y'] = $y;
220		}
221
222		return $this->createConnection($photo, 'tags', $data);
223	}
224
225	/**
226	 * Method to get the album-sized view of the photo. Requires authentication and user_photos or friends_photos permission for private photos.
227	 *
228	 * @param   string   $photo     The photo id.
229	 * @param   boolean  $redirect  If false this will return the URL of the picture without a 302 redirect.
230	 *
231	 * @return  string  URL of the picture.
232	 *
233	 * @since   13.1
234	 */
235	public function getPicture($photo, $redirect = true)
236	{
237		$extra_fields = '';
238
239		if ($redirect == false)
240		{
241			$extra_fields = '?redirect=false';
242		}
243
244		return $this->getConnection($photo, 'picture', $extra_fields);
245	}
246}