1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage Twitter
5 *
6 * @copyright Copyright (C) 2005 - 2017 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 * @since 12.3
16 * @deprecated 4.0 Use the `joomla/twitter` package via Composer instead
17 */
18 class JTwitterLists extends JTwitterObject
19 {
20 /**
21 * Method to get all lists the authenticating or specified user subscribes to, including their own.
22 *
23 * @param mixed $user Either an integer containing the user ID or a string containing the screen name.
24 * @param boolean $reverse Set this to true if you would like owned lists to be returned first. See description
25 * above for information on how this parameter works.
26 *
27 * @return array The decoded JSON response
28 *
29 * @since 12.3
30 * @throws RuntimeException
31 */
32 public function getLists($user, $reverse = null)
33 {
34 // Check the rate limit for remaining hits
35 $this->checkRateLimit('lists', 'list');
36
37 // Determine which type of data was passed for $user
38 if (is_numeric($user))
39 {
40 $data['user_id'] = $user;
41 }
42 elseif (is_string($user))
43 {
44 $data['screen_name'] = $user;
45 }
46 else
47 {
48 // We don't have a valid entry
49 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
50 }
51
52 // Check if reverse is specified.
53 if (!is_null($reverse))
54 {
55 $data['reverse'] = $reverse;
56 }
57
58 // Set the API path
59 $path = '/lists/list.json';
60
61 // Send the request.
62 return $this->sendRequest($path, 'GET', $data);
63 }
64
65 /**
66 * Method to get tweet timeline for members of the specified list
67 *
68 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
69 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
70 * @param integer $since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
71 * @param integer $max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
72 * @param integer $count Specifies the number of results to retrieve per "page."
73 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
74 * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
75 * @param boolean $include_rts When set to either true, t or 1, the list timeline will contain native retweets (if they exist) in addition
76 * to the standard stream of tweets.
77 *
78 * @return array The decoded JSON response
79 *
80 * @since 12.3
81 * @throws RuntimeException
82 */
83 public function getStatuses($list, $owner = null, $since_id = 0, $max_id = 0, $count = 0, $entities = null, $include_rts = null)
84 {
85 // Check the rate limit for remaining hits
86 $this->checkRateLimit('lists', 'statuses');
87
88 // Determine which type of data was passed for $list
89 if (is_numeric($list))
90 {
91 $data['list_id'] = $list;
92 }
93 elseif (is_string($list))
94 {
95 $data['slug'] = $list;
96
97 // In this case the owner is required.
98 if (is_numeric($owner))
99 {
100 $data['owner_id'] = $owner;
101 }
102 elseif (is_string($owner))
103 {
104 $data['owner_screen_name'] = $owner;
105 }
106 else
107 {
108 // We don't have a valid entry
109 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
110 }
111 }
112 else
113 {
114 // We don't have a valid entry
115 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
116 }
117
118 // Set the API path
119 $path = '/lists/statuses.json';
120
121 // Check if since_id is specified
122 if ($since_id > 0)
123 {
124 $data['since_id'] = $since_id;
125 }
126
127 // Check if max_id is specified
128 if ($max_id > 0)
129 {
130 $data['max_id'] = $max_id;
131 }
132
133 // Check if count is specified
134 if ($count > 0)
135 {
136 $data['count'] = $count;
137 }
138
139 // Check if entities is specified
140 if (!is_null($entities))
141 {
142 $data['include_entities'] = $entities;
143 }
144
145 // Check if include_rts is specified
146 if (!is_null($include_rts))
147 {
148 $data['include_rts'] = $include_rts;
149 }
150
151 // Send the request.
152 return $this->sendRequest($path, 'GET', $data);
153 }
154
155 /**
156 * Method to get the subscribers of the specified list.
157 *
158 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
159 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
160 * @param integer $cursor Breaks the results into pages. A single page contains 20 lists. Provide a value of -1 to begin paging.
161 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
162 * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
163 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
164 *
165 * @return array The decoded JSON response
166 *
167 * @since 12.3
168 * @throws RuntimeException
169 */
170 public function getSubscribers($list, $owner = null, $cursor = null, $entities = null, $skip_status = null)
171 {
172 // Check the rate limit for remaining hits
173 $this->checkRateLimit('lists', 'subscribers');
174
175 // Determine which type of data was passed for $list
176 if (is_numeric($list))
177 {
178 $data['list_id'] = $list;
179 }
180 elseif (is_string($list))
181 {
182 $data['slug'] = $list;
183
184 // In this case the owner is required.
185 if (is_numeric($owner))
186 {
187 $data['owner_id'] = $owner;
188 }
189 elseif (is_string($owner))
190 {
191 $data['owner_screen_name'] = $owner;
192 }
193 else
194 {
195 // We don't have a valid entry
196 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
197 }
198 }
199 else
200 {
201 // We don't have a valid entry
202 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
203 }
204
205 // Set the API path
206 $path = '/lists/subscribers.json';
207
208 // Check if cursor is specified
209 if (!is_null($cursor))
210 {
211 $data['cursor'] = $cursor;
212 }
213
214 // Check if entities is specified
215 if (!is_null($entities))
216 {
217 $data['include_entities'] = $entities;
218 }
219
220 // Check if skip_status is specified
221 if (!is_null($skip_status))
222 {
223 $data['skip_status'] = $skip_status;
224 }
225
226 // Send the request.
227 return $this->sendRequest($path, 'GET', $data);
228 }
229
230 /**
231 * Method to remove multiple members from a list, by specifying a comma-separated list of member ids or screen names.
232 *
233 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
234 * @param string $user_id A comma separated list of user IDs, up to 100 are allowed in a single request.
235 * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
236 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
237 *
238 * @return array The decoded JSON response
239 *
240 * @since 12.3
241 * @throws RuntimeException
242 */
243 public function deleteMembers($list, $user_id = null, $screen_name = null, $owner = null)
244 {
245 // Determine which type of data was passed for $list
246 if (is_numeric($list))
247 {
248 $data['list_id'] = $list;
249 }
250 elseif (is_string($list))
251 {
252 $data['slug'] = $list;
253
254 // In this case the owner is required.
255 if (is_numeric($owner))
256 {
257 $data['owner_id'] = $owner;
258 }
259 elseif (is_string($owner))
260 {
261 $data['owner_screen_name'] = $owner;
262 }
263 else
264 {
265 // We don't have a valid entry
266 throw new RuntimeException('The specified username for owner is not in the correct format; must use integer or string');
267 }
268 }
269 else
270 {
271 // We don't have a valid entry
272 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
273 }
274
275 if ($user_id)
276 {
277 $data['user_id'] = $user_id;
278 }
279
280 if ($screen_name)
281 {
282 $data['screen_name'] = $screen_name;
283 }
284
285 if ($user_id == null && $screen_name == null)
286 {
287 // We don't have a valid entry
288 throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
289 }
290
291 // Set the API path
292 $path = '/lists/members/destroy_all.json';
293
294 // Send the request.
295 return $this->sendRequest($path, 'POST', $data);
296 }
297
298 /**
299 * Method to subscribe the authenticated user to the specified list.
300 *
301 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
302 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
303 *
304 * @return array The decoded JSON response
305 *
306 * @since 12.3
307 * @throws RuntimeException
308 */
309 public function subscribe($list, $owner = null)
310 {
311 // Check the rate limit for remaining hits
312 $this->checkRateLimit('lists', 'subscribers/create');
313
314 // Determine which type of data was passed for $list
315 if (is_numeric($list))
316 {
317 $data['list_id'] = $list;
318 }
319 elseif (is_string($list))
320 {
321 $data['slug'] = $list;
322
323 // In this case the owner is required.
324 if (is_numeric($owner))
325 {
326 $data['owner_id'] = $owner;
327 }
328 elseif (is_string($owner))
329 {
330 $data['owner_screen_name'] = $owner;
331 }
332 else
333 {
334 // We don't have a valid entry
335 throw new RuntimeException('The specified username for owner is not in the correct format; must use integer or string');
336 }
337 }
338 else
339 {
340 // We don't have a valid entry
341 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
342 }
343
344 // Set the API path
345 $path = '/lists/subscribers/create.json';
346
347 // Send the request.
348 return $this->sendRequest($path, 'POST', $data);
349 }
350
351 /**
352 * Method to check if the specified user is a member of the specified list.
353 *
354 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
355 * @param mixed $user Either an integer containing the user ID or a string containing the screen name of the user to remove.
356 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
357 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a
358 * variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
359 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
360 *
361 * @return array The decoded JSON response
362 *
363 * @since 12.3
364 * @throws RuntimeException
365 */
366 public function isMember($list, $user, $owner = null, $entities = null, $skip_status = null)
367 {
368 // Check the rate limit for remaining hits
369 $this->checkRateLimit('lists', 'members/show');
370
371 // Determine which type of data was passed for $list
372 if (is_numeric($list))
373 {
374 $data['list_id'] = $list;
375 }
376 elseif (is_string($list))
377 {
378 $data['slug'] = $list;
379
380 // In this case the owner is required.
381 if (is_numeric($owner))
382 {
383 $data['owner_id'] = $owner;
384 }
385 elseif (is_string($owner))
386 {
387 $data['owner_screen_name'] = $owner;
388 }
389 else
390 {
391 // We don't have a valid entry
392 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
393 }
394 }
395 else
396 {
397 // We don't have a valid entry
398 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
399 }
400
401 if (is_numeric($user))
402 {
403 $data['user_id'] = $user;
404 }
405 elseif (is_string($user))
406 {
407 $data['screen_name'] = $user;
408 }
409 else
410 {
411 // We don't have a valid entry
412 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
413 }
414
415 // Set the API path
416 $path = '/lists/members/show.json';
417
418 // Check if entities is specified
419 if (!is_null($entities))
420 {
421 $data['include_entities'] = $entities;
422 }
423
424 // Check if skip_status is specified
425 if (!is_null($skip_status))
426 {
427 $data['skip_status'] = $skip_status;
428 }
429
430 // Send the request.
431 return $this->sendRequest($path, 'GET', $data);
432 }
433
434 /**
435 * Method to check if the specified user is a subscriber of the specified list.
436 *
437 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
438 * @param mixed $user Either an integer containing the user ID or a string containing the screen name of the user to remove.
439 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
440 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a
441 * variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
442 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
443 *
444 * @return array The decoded JSON response
445 *
446 * @since 12.3
447 * @throws RuntimeException
448 */
449 public function isSubscriber($list, $user, $owner = null, $entities = null, $skip_status = null)
450 {
451 // Check the rate limit for remaining hits
452 $this->checkRateLimit('lists', 'subscribers/show');
453
454 // Determine which type of data was passed for $list
455 if (is_numeric($list))
456 {
457 $data['list_id'] = $list;
458 }
459 elseif (is_string($list))
460 {
461 $data['slug'] = $list;
462
463 // In this case the owner is required.
464 if (is_numeric($owner))
465 {
466 $data['owner_id'] = $owner;
467 }
468 elseif (is_string($owner))
469 {
470 $data['owner_screen_name'] = $owner;
471 }
472 else
473 {
474 // We don't have a valid entry
475 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
476 }
477 }
478 else
479 {
480 // We don't have a valid entry
481 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
482 }
483
484 if (is_numeric($user))
485 {
486 $data['user_id'] = $user;
487 }
488 elseif (is_string($user))
489 {
490 $data['screen_name'] = $user;
491 }
492 else
493 {
494 // We don't have a valid entry
495 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
496 }
497
498 // Set the API path
499 $path = '/lists/subscribers/show.json';
500
501 // Check if entities is specified
502 if (!is_null($entities))
503 {
504 $data['include_entities'] = $entities;
505 }
506
507 // Check if skip_status is specified
508 if (!is_null($skip_status))
509 {
510 $data['skip_status'] = $skip_status;
511 }
512
513 // Send the request.
514 return $this->sendRequest($path, 'GET', $data);
515 }
516
517 /**
518 * Method to unsubscribe the authenticated user from the specified list.
519 *
520 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
521 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
522 *
523 * @return array The decoded JSON response
524 *
525 * @since 12.3
526 * @throws RuntimeException
527 */
528 public function unsubscribe($list, $owner = null)
529 {
530 // Check the rate limit for remaining hits
531 $this->checkRateLimit('lists', 'subscribers/destroy');
532
533 // Determine which type of data was passed for $list
534 if (is_numeric($list))
535 {
536 $data['list_id'] = $list;
537 }
538 elseif (is_string($list))
539 {
540 $data['slug'] = $list;
541
542 // In this case the owner is required.
543 if (is_numeric($owner))
544 {
545 $data['owner_id'] = $owner;
546 }
547 elseif (is_string($owner))
548 {
549 $data['owner_screen_name'] = $owner;
550 }
551 else
552 {
553 // We don't have a valid entry
554 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
555 }
556 }
557 else
558 {
559 // We don't have a valid entry
560 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
561 }
562
563 // Set the API path
564 $path = '/lists/subscribers/destroy.json';
565
566 // Send the request.
567 return $this->sendRequest($path, 'POST', $data);
568 }
569
570 /**
571 * Method to add multiple members to a list, by specifying a comma-separated list of member ids or screen names.
572 *
573 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
574 * @param string $user_id A comma separated list of user IDs, up to 100 are allowed in a single request.
575 * @param string $screen_name A comma separated list of screen names, up to 100 are allowed in a single request.
576 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name of the owner.
577 *
578 * @return array The decoded JSON response
579 *
580 * @since 12.3
581 * @throws RuntimeException
582 */
583 public function addMembers($list, $user_id = null, $screen_name = null, $owner = null)
584 {
585 // Check the rate limit for remaining hits
586 $this->checkRateLimit('lists', 'members/create_all');
587
588 // Determine which type of data was passed for $list
589 if (is_numeric($list))
590 {
591 $data['list_id'] = $list;
592 }
593 elseif (is_string($list))
594 {
595 $data['slug'] = $list;
596
597 // In this case the owner is required.
598 if (is_numeric($owner))
599 {
600 $data['owner_id'] = $owner;
601 }
602 elseif (is_string($owner))
603 {
604 $data['owner_screen_name'] = $owner;
605 }
606 else
607 {
608 // We don't have a valid entry
609 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
610 }
611 }
612 else
613 {
614 // We don't have a valid entry
615 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
616 }
617
618 if ($user_id)
619 {
620 $data['user_id'] = $user_id;
621 }
622
623 if ($screen_name)
624 {
625 $data['screen_name'] = $screen_name;
626 }
627
628 if ($user_id == null && $screen_name == null)
629 {
630 // We don't have a valid entry
631 throw new RuntimeException('You must specify either a comma separated list of screen names, user IDs, or a combination of the two');
632 }
633
634 // Set the API path
635 $path = '/lists/members/create_all.json';
636
637 // Send the request.
638 return $this->sendRequest($path, 'POST', $data);
639 }
640
641 /**
642 * Method to get the members of the specified list.
643 *
644 * @param mixed $list Either an integer containing the list ID or a string containing the list slug.
645 * @param mixed $owner Either an integer containing the user ID or a string containing the screen name.
646 * @param boolean $entities When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety
647 * of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags.
648 * @param boolean $skip_status When set to either true, t or 1 statuses will not be included in the returned user objects.
649 *
650 * @return array The decoded JSON response
651 *
652 * @since 12.3
653 * @throws RuntimeException
654 */
655 public function getMembers($list, $owner = null, $entities = null, $skip_status = null)
656 {
657 // Check the rate limit for remaining hits
658 $this->checkRateLimit('lists', 'members');
659
660 // Determine which type of data was passed for $list
661 if (is_numeric($list))
662 {
663 $data['list_id'] = $list;
664 }
665 elseif (is_string($list))
666 {
667 $data['slug'] = $list;
668
669 // In this case the owner is required.
670 if (is_numeric($owner))
671 {
672 $data['owner_id'] = $owner;
673 }
674 elseif (is_string($owner))
675 {
676 $data['owner_screen_name'] = $owner;
677 }
678 else
679 {
680 // We don't have a valid entry
681 throw new RuntimeException('The specified username is not in the correct format; must use integer or string');
682 }
683 }
684 else
685 {
686 // We don't have a valid entry
687 throw new RuntimeException('The specified list is not in the correct format; must use integer or string');
688 }
689
690 // Set the API path
691 $path = '/lists/members.json';
692
693 // Check if entities is specified
694 if (!is_null($entities))
695 {
696 $data['include_entities'] = $entities;
697 }
698
699 // Check if skip_status is specified
700 if (!is_null($skip_status))
701 {
702 $data['skip_status'] = $skip_status;
703 }
704
705 // Send the request.
706 return $this->sendRequest($path, 'GET', $data);
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 }
983