Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
lists.php
Aller à la documentation de ce fichier.
1 <?php
2 /**
3  * @package Joomla.Platform
4  * @subpackage Twitter
5  *
6  * @copyright Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
7  * @license GNU General Public License version 2 or later; see LICENSE
8  */
9 
10 defined('JPATH_PLATFORM') or die();
11 
12 /**
13  * Twitter API Lists class for the Joomla Platform.
14  *
15  * @package Joomla.Platform
16  * @subpackage Twitter
17  * @since 12.3
18  */
19 class JTwitterLists extends JTwitterObject
20 {
21  /**
22  * Method to get all lists the authenticating or specified user subscribes to, including their own.
23  *
24  * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
25  * @param boolean $reverse Set this to true if you would like owned lists to be returned first. See description
26  * above for information on how this parameter works.
27  *
28  * @return array The decoded JSON response
29  *
30  * @since 12.3
31  * @throws RuntimeException
32  */
33  public function getLists($user, $reverse = null)
34  {
35  // Check the rate limit for remaining hits
36  $this->checkRateLimit('lists', 'list');
37 
38  // Determine which type of data was passed for $user
39  if (is_numeric($user))
40  {
41  $data['user_id'] = $user;
42  }
43  elseif (is_string($user))
44  {
45  $data['screen_name'] = $user;
46  }
47  else
48  {
49  // We don't have a valid entry
50  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
51  }
52 
53  // Check if reverse is specified.
54  if (!is_null($reverse))
55  {
56  $data['reverse'] = $reverse;
57  }
58 
59  // Set the API path
60  $path = '/lists/list.json';
61 
62  // Send the request.
63  return $this->sendRequest($path, 'GET', $data);
64  }
65 
66  /**
67  * Method to get tweet timeline for members of the specified list
68  *
69  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
70  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
71  * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
72  * @param integer $max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
73  * @param integer $count Specifies the number of results to retrieve per "page."
74  * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
75  * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
76  * @param boolean $include_rts When set to either true, t or 1, the list timeline will contain native retweets (if they exist) in addition
77  * to the standard stream of tweets.
78  *
79  * @return array The decoded JSON response
80  *
81  * @since 12.3
82  * @throws RuntimeException
83  */
84  public function getStatuses($list, $owner = null, $since_id = 0, $max_id = 0, $count = 0, $entities = null, $include_rts = null)
85  {
86  // Check the rate limit for remaining hits
87  $this->checkRateLimit('lists', 'statuses');
88 
89  // Determine which type of data was passed for $list
90  if (is_numeric($list))
91  {
92  $data['list_id'] = $list;
93  }
94  elseif (is_string($list))
95  {
96  $data['slug'] = $list;
97 
98  // In this case the owner is required.
99  if (is_numeric($owner))
100  {
101  $data['owner_id'] = $owner;
102  }
103  elseif (is_string($owner))
104  {
105  $data['owner_screen_name'] = $owner;
106  }
107  else
108  {
109  // We don't have a valid entry
110  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
111  }
112  }
113  else
114  {
115  // We don't have a valid entry
116  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
117  }
118 
119  // Set the API path
120  $path = '/lists/statuses.json';
121 
122  // Check if since_id is specified
123  if ($since_id > 0)
124  {
125  $data['since_id'] = $since_id;
126  }
127 
128  // Check if max_id is specified
129  if ($max_id > 0)
130  {
131  $data['max_id'] = $max_id;
132  }
133 
134  // Check if count is specified
135  if ($count > 0)
136  {
137  $data['count'] = $count;
138  }
139 
140  // Check if entities is specified
141  if (!is_null($entities))
142  {
143  $data['include_entities'] = $entities;
144  }
145 
146  // Check if include_rts is specified
147  if (!is_null($include_rts))
148  {
149  $data['include_rts'] = $include_rts;
150  }
151 
152  // Send the request.
153  return $this->sendRequest($path, 'GET', $data);
154 
155  }
156 
157  /**
158  * Method to get the subscribers of the specified list.
159  *
160  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
161  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
162  * @param integer $cursor Breaks the results into pages. A single page contains 20 lists. Provide a value of -1 to begin paging.
163  * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
164  * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
165  * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
166  *
167  * @return array The decoded JSON response
168  *
169  * @since 12.3
170  * @throws RuntimeException
171  */
172  public function getSubscribers($list, $owner = null, $cursor = null, $entities = null, $skip_status = null)
173  {
174  // Check the rate limit for remaining hits
175  $this->checkRateLimit('lists', 'subscribers');
176 
177  // Determine which type of data was passed for $list
178  if (is_numeric($list))
179  {
180  $data['list_id'] = $list;
181  }
182  elseif (is_string($list))
183  {
184  $data['slug'] = $list;
185 
186  // In this case the owner is required.
187  if (is_numeric($owner))
188  {
189  $data['owner_id'] = $owner;
190  }
191  elseif (is_string($owner))
192  {
193  $data['owner_screen_name'] = $owner;
194  }
195  else
196  {
197  // We don't have a valid entry
198  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
199  }
200  }
201  else
202  {
203  // We don't have a valid entry
204  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
205  }
206 
207  // Set the API path
208  $path = '/lists/subscribers.json';
209 
210  // Check if cursor is specified
211  if (!is_null($cursor))
212  {
213  $data['cursor'] = $cursor;
214  }
215 
216  // Check if entities is specified
217  if (!is_null($entities))
218  {
219  $data['include_entities'] = $entities;
220  }
221 
222  // Check if skip_status is specified
223  if (!is_null($skip_status))
224  {
225  $data['skip_status'] = $skip_status;
226  }
227 
228  // Send the request.
229  return $this->sendRequest($path, 'GET', $data);
230 
231  }
232 
233  /**
234  * Method to remove multiple members from a list, by specifying a comma-separated list of member ids or screen names.
235  *
236  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
237  * @param string $user_id A comma separated list of user IDs, up to 100 are allowed in a single request.
238  * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
239  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
240  *
241  * @return array The decoded JSON response
242  *
243  * @since 12.3
244  * @throws RuntimeException
245  */
246  public function deleteMembers($list, $user_id = null, $screen_name = null, $owner = null)
247  {
248  // Determine which type of data was passed for $list
249  if (is_numeric($list))
250  {
251  $data['list_id'] = $list;
252  }
253  elseif (is_string($list))
254  {
255  $data['slug'] = $list;
256 
257  // In this case the owner is required.
258  if (is_numeric($owner))
259  {
260  $data['owner_id'] = $owner;
261  }
262  elseif (is_string($owner))
263  {
264  $data['owner_screen_name'] = $owner;
265  }
266  else
267  {
268  // We don't have a valid entry
269  throw new RuntimeException('The specified username for owner is not in the correct format; must use integer or string');
270  }
271  }
272  else
273  {
274  // We don't have a valid entry
275  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
276  }
277 
278  if ($user_id)
279  {
280  $data['user_id'] = $user_id;
281  }
282  if ($screen_name)
283  {
284  $data['screen_name'] = $screen_name;
285  }
286  if ($user_id == null && $screen_name == null)
287  {
288  // We don't have a valid entry
289  throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
290  }
291 
292  // Set the API path
293  $path = '/lists/members/destroy_all.json';
294 
295  // Send the request.
296  return $this->sendRequest($path, 'POST', $data);
297  }
298 
299  /**
300  * Method to subscribe the authenticated user to the specified list.
301  *
302  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
303  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
304  *
305  * @return array The decoded JSON response
306  *
307  * @since 12.3
308  * @throws RuntimeException
309  */
310  public function subscribe($list, $owner = null)
311  {
312  // Check the rate limit for remaining hits
313  $this->checkRateLimit('lists', 'subscribers/create');
314 
315  // Determine which type of data was passed for $list
316  if (is_numeric($list))
317  {
318  $data['list_id'] = $list;
319  }
320  elseif (is_string($list))
321  {
322  $data['slug'] = $list;
323 
324  // In this case the owner is required.
325  if (is_numeric($owner))
326  {
327  $data['owner_id'] = $owner;
328  }
329  elseif (is_string($owner))
330  {
331  $data['owner_screen_name'] = $owner;
332  }
333  else
334  {
335  // We don't have a valid entry
336  throw new RuntimeException('The specified username for owner is not in the correct format; must use integer or string');
337  }
338  }
339  else
340  {
341  // We don't have a valid entry
342  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
343  }
344 
345  // Set the API path
346  $path = '/lists/subscribers/create.json';
347 
348  // Send the request.
349  return $this->sendRequest($path, 'POST', $data);
350  }
351 
352  /**
353  * Method to check if the specified user is a member of the specified list.
354  *
355  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
356  * @param mixed $user Either an integer containing the user ID or a string containing the screen name of the user to remove.
357  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
358  * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a
359  * variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
360  * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
361  *
362  * @return array The decoded JSON response
363  *
364  * @since 12.3
365  * @throws RuntimeException
366  */
367  public function isMember($list, $user, $owner = null, $entities = null, $skip_status = null)
368  {
369  // Check the rate limit for remaining hits
370  $this->checkRateLimit('lists', 'members/show');
371 
372  // Determine which type of data was passed for $list
373  if (is_numeric($list))
374  {
375  $data['list_id'] = $list;
376  }
377  elseif (is_string($list))
378  {
379  $data['slug'] = $list;
380 
381  // In this case the owner is required.
382  if (is_numeric($owner))
383  {
384  $data['owner_id'] = $owner;
385  }
386  elseif (is_string($owner))
387  {
388  $data['owner_screen_name'] = $owner;
389  }
390  else
391  {
392  // We don't have a valid entry
393  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
394  }
395  }
396  else
397  {
398  // We don't have a valid entry
399  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
400  }
401 
402  if (is_numeric($user))
403  {
404  $data['user_id'] = $user;
405  }
406  elseif (is_string($user))
407  {
408  $data['screen_name'] = $user;
409  }
410  else
411  {
412  // We don't have a valid entry
413  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
414  }
415 
416  // Set the API path
417  $path = '/lists/members/show.json';
418 
419  // Check if entities is specified
420  if (!is_null($entities))
421  {
422  $data['include_entities'] = $entities;
423  }
424 
425  // Check if skip_status is specified
426  if (!is_null($skip_status))
427  {
428  $data['skip_status'] = $skip_status;
429  }
430 
431  // Send the request.
432  return $this->sendRequest($path, 'GET', $data);
433  }
434 
435  /**
436  * Method to check if the specified user is a subscriber of the specified list.
437  *
438  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
439  * @param mixed $user Either an integer containing the user ID or a string containing the screen name of the user to remove.
440  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
441  * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a
442  * variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
443  * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
444  *
445  * @return array The decoded JSON response
446  *
447  * @since 12.3
448  * @throws RuntimeException
449  */
450  public function isSubscriber($list, $user, $owner = null, $entities = null, $skip_status = null)
451  {
452  // Check the rate limit for remaining hits
453  $this->checkRateLimit('lists', 'subscribers/show');
454 
455  // Determine which type of data was passed for $list
456  if (is_numeric($list))
457  {
458  $data['list_id'] = $list;
459  }
460  elseif (is_string($list))
461  {
462  $data['slug'] = $list;
463 
464  // In this case the owner is required.
465  if (is_numeric($owner))
466  {
467  $data['owner_id'] = $owner;
468  }
469  elseif (is_string($owner))
470  {
471  $data['owner_screen_name'] = $owner;
472  }
473  else
474  {
475  // We don't have a valid entry
476  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
477  }
478  }
479  else
480  {
481  // We don't have a valid entry
482  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
483  }
484 
485  if (is_numeric($user))
486  {
487  $data['user_id'] = $user;
488  }
489  elseif (is_string($user))
490  {
491  $data['screen_name'] = $user;
492  }
493  else
494  {
495  // We don't have a valid entry
496  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
497  }
498 
499  // Set the API path
500  $path = '/lists/subscribers/show.json';
501 
502  // Check if entities is specified
503  if (!is_null($entities))
504  {
505  $data['include_entities'] = $entities;
506  }
507 
508  // Check if skip_status is specified
509  if (!is_null($skip_status))
510  {
511  $data['skip_status'] = $skip_status;
512  }
513 
514  // Send the request.
515  return $this->sendRequest($path, 'GET', $data);
516  }
517 
518  /**
519  * Method to unsubscribe the authenticated user from the specified list.
520  *
521  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
522  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
523  *
524  * @return array The decoded JSON response
525  *
526  * @since 12.3
527  * @throws RuntimeException
528  */
529  public function unsubscribe($list, $owner = null)
530  {
531  // Check the rate limit for remaining hits
532  $this->checkRateLimit('lists', 'subscribers/destroy');
533 
534  // Determine which type of data was passed for $list
535  if (is_numeric($list))
536  {
537  $data['list_id'] = $list;
538  }
539  elseif (is_string($list))
540  {
541  $data['slug'] = $list;
542 
543  // In this case the owner is required.
544  if (is_numeric($owner))
545  {
546  $data['owner_id'] = $owner;
547  }
548  elseif (is_string($owner))
549  {
550  $data['owner_screen_name'] = $owner;
551  }
552  else
553  {
554  // We don't have a valid entry
555  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
556  }
557  }
558  else
559  {
560  // We don't have a valid entry
561  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
562  }
563 
564  // Set the API path
565  $path = '/lists/subscribers/destroy.json';
566 
567  // Send the request.
568  return $this->sendRequest($path, 'POST', $data);
569  }
570 
571  /**
572  * Method to add multiple members to a list, by specifying a comma-separated list of member ids or screen names.
573  *
574  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
575  * @param string $user_id A comma separated list of user IDs, up to 100 are allowed in a single request.
576  * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
577  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
578  *
579  * @return array The decoded JSON response
580  *
581  * @since 12.3
582  * @throws RuntimeException
583  */
584  public function addMembers($list, $user_id = null, $screen_name = null, $owner = null)
585  {
586  // Check the rate limit for remaining hits
587  $this->checkRateLimit('lists', 'members/create_all');
588 
589  // Determine which type of data was passed for $list
590  if (is_numeric($list))
591  {
592  $data['list_id'] = $list;
593  }
594  elseif (is_string($list))
595  {
596  $data['slug'] = $list;
597 
598  // In this case the owner is required.
599  if (is_numeric($owner))
600  {
601  $data['owner_id'] = $owner;
602  }
603  elseif (is_string($owner))
604  {
605  $data['owner_screen_name'] = $owner;
606  }
607  else
608  {
609  // We don't have a valid entry
610  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
611  }
612  }
613  else
614  {
615  // We don't have a valid entry
616  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
617  }
618 
619  if ($user_id)
620  {
621  $data['user_id'] = $user_id;
622  }
623  if ($screen_name)
624  {
625  $data['screen_name'] = $screen_name;
626  }
627  if ($user_id == null && $screen_name == null)
628  {
629  // We don't have a valid entry
630  throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
631  }
632 
633  // Set the API path
634  $path = '/lists/members/create_all.json';
635 
636  // Send the request.
637  return $this->sendRequest($path, 'POST', $data);
638  }
639 
640  /**
641  * Method to get the members of the specified list.
642  *
643  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
644  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
645  * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
646  * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
647  * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
648  *
649  * @return array The decoded JSON response
650  *
651  * @since 12.3
652  * @throws RuntimeException
653  */
654  public function getMembers($list, $owner = null, $entities = null, $skip_status = null)
655  {
656  // Check the rate limit for remaining hits
657  $this->checkRateLimit('lists', 'members');
658 
659  // Determine which type of data was passed for $list
660  if (is_numeric($list))
661  {
662  $data['list_id'] = $list;
663  }
664  elseif (is_string($list))
665  {
666  $data['slug'] = $list;
667 
668  // In this case the owner is required.
669  if (is_numeric($owner))
670  {
671  $data['owner_id'] = $owner;
672  }
673  elseif (is_string($owner))
674  {
675  $data['owner_screen_name'] = $owner;
676  }
677  else
678  {
679  // We don't have a valid entry
680  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
681  }
682  }
683  else
684  {
685  // We don't have a valid entry
686  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
687  }
688 
689  // Set the API path
690  $path = '/lists/members.json';
691 
692  // Check if entities is specified
693  if (!is_null($entities))
694  {
695  $data['include_entities'] = $entities;
696  }
697 
698  // Check if skip_status is specified
699  if (!is_null($skip_status))
700  {
701  $data['skip_status'] = $skip_status;
702  }
703 
704  // Send the request.
705  return $this->sendRequest($path, 'GET', $data);
706 
707  }
708 
709  /**
710  * Method to get the specified list.
711  *
712  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
713  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
714  *
715  * @return array The decoded JSON response
716  *
717  * @since 12.3
718  * @throws RuntimeException
719  */
720  public function getListById($list, $owner = null)
721  {
722  // Check the rate limit for remaining hits
723  $this->checkRateLimit('lists', 'show');
724 
725  // Determine which type of data was passed for $list
726  if (is_numeric($list))
727  {
728  $data['list_id'] = $list;
729  }
730  elseif (is_string($list))
731  {
732  $data['slug'] = $list;
733 
734  // In this case the owner is required.
735  if (is_numeric($owner))
736  {
737  $data['owner_id'] = $owner;
738  }
739  elseif (is_string($owner))
740  {
741  $data['owner_screen_name'] = $owner;
742  }
743  else
744  {
745  // We don't have a valid entry
746  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
747  }
748  }
749  else
750  {
751  // We don't have a valid entry
752  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
753  }
754 
755  // Set the API path
756  $path = '/lists/show.json';
757 
758  // Send the request.
759  return $this->sendRequest($path, 'GET', $data);
760  }
761 
762  /**
763  * Method to get a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user's own lists.
764  *
765  * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
766  * @param integer $count The amount of results to return per page. Defaults to 20. Maximum of 1,000 when using cursors.
767  * @param integer $cursor Breaks the results into pages. Provide a value of -1 to begin paging.
768  *
769  * @return array The decoded JSON response
770  *
771  * @since 12.3
772  * @throws RuntimeException
773  */
774  public function getSubscriptions($user, $count = 0, $cursor = null)
775  {
776  // Check the rate limit for remaining hits
777  $this->checkRateLimit('lists', 'subscriptions');
778 
779  // Determine which type of data was passed for $user
780  if (is_numeric($user))
781  {
782  $data['user_id'] = $user;
783  }
784  elseif (is_string($user))
785  {
786  $data['screen_name'] = $user;
787  }
788  else
789  {
790  // We don't have a valid entry
791  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
792  }
793 
794  // Check if count is specified.
795  if ($count > 0)
796  {
797  $data['count'] = $count;
798  }
799 
800  // Check if cursor is specified.
801  if (!is_null($cursor))
802  {
803  $data['cursor'] = $cursor;
804  }
805 
806  // Set the API path
807  $path = '/lists/subscriptions.json';
808 
809  // Send the request.
810  return $this->sendRequest($path, 'GET', $data);
811  }
812 
813  /**
814  * Method to update the specified list
815  *
816  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
817  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
818  * @param string $name The name of the list.
819  * @param string $mode Whether your list is public or private. Values can be public or private. If no mode is
820  * specified the list will be public.
821  * @param string $description The description to give the list.
822  *
823  * @return array The decoded JSON response
824  *
825  * @since 12.3
826  * @throws RuntimeException
827  */
828  public function update($list, $owner = null, $name = null, $mode = null, $description = null)
829  {
830  // Check the rate limit for remaining hits
831  $this->checkRateLimit('lists', 'update');
832 
833  // Determine which type of data was passed for $list
834  if (is_numeric($list))
835  {
836  $data['list_id'] = $list;
837  }
838  elseif (is_string($list))
839  {
840  $data['slug'] = $list;
841 
842  // In this case the owner is required.
843  if (is_numeric($owner))
844  {
845  $data['owner_id'] = $owner;
846  }
847  elseif (is_string($owner))
848  {
849  $data['owner_screen_name'] = $owner;
850  }
851  else
852  {
853  // We don't have a valid entry
854  throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
855  }
856  }
857  else
858  {
859  // We don't have a valid entry
860  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
861  }
862 
863  // Check if name is specified.
864  if ($name)
865  {
866  $data['name'] = $name;
867  }
868 
869  // Check if mode is specified.
870  if ($mode)
871  {
872  $data['mode'] = $mode;
873  }
874 
875  // Check if description is specified.
876  if ($description)
877  {
878  $data['description'] = $description;
879  }
880 
881  // Set the API path
882  $path = '/lists/update.json';
883 
884  // Send the request.
885  return $this->sendRequest($path, 'POST', $data);
886  }
887 
888  /**
889  * Method to create a new list for the authenticated user.
890  *
891  * @param string $name The name of the list.
892  * @param string $mode Whether your list is public or private. Values can be public or private. If no mode is
893  * specified the list will be public.
894  * @param string $description The description to give the list.
895  *
896  * @return array The decoded JSON response
897  *
898  * @since 12.3
899  */
900  public function create($name, $mode = null, $description = null)
901  {
902  // Check the rate limit for remaining hits
903  $this->checkRateLimit('lists', 'create');
904 
905  // Check if name is specified.
906  if ($name)
907  {
908  $data['name'] = $name;
909  }
910 
911  // Check if mode is specified.
912  if ($mode)
913  {
914  $data['mode'] = $mode;
915  }
916 
917  // Check if description is specified.
918  if ($description)
919  {
920  $data['description'] = $description;
921  }
922 
923  // Set the API path
924  $path = '/lists/create.json';
925 
926  // Send the request.
927  return $this->sendRequest($path, 'POST', $data);
928  }
929 
930  /**
931  * Method to delete a specified list.
932  *
933  * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
934  * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
935  *
936  * @return array The decoded JSON response
937  *
938  * @since 12.3
939  * @throws RuntimeException
940  */
941  public function delete($list, $owner = null)
942  {
943  // Check the rate limit for remaining hits
944  $this->checkRateLimit('lists', 'destroy');
945 
946  // Determine which type of data was passed for $list
947  if (is_numeric($list))
948  {
949  $data['list_id'] = $list;
950  }
951  elseif (is_string($list))
952  {
953  $data['slug'] = $list;
954 
955  // In this case the owner is required.
956  if (is_numeric($owner))
957  {
958  $data['owner_id'] = $owner;
959  }
960  elseif (is_string($owner))
961  {
962  $data['owner_screen_name'] = $owner;
963  }
964  else
965  {
966  // We don't have a valid entry
967  throw new RuntimeException('The specified username for owner is not in the correct format; must use integer or string');
968  }
969  }
970  else
971  {
972  // We don't have a valid entry
973  throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
974  }
975 
976  // Set the API path
977  $path = '/lists/destroy.json';
978 
979  // Send the request.
980  return $this->sendRequest($path, 'POST', $data);
981  }
982 }