Source for file lists.php

Documentation is available at lists.php

  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. }

Documentation generated on Tue, 19 Nov 2013 15:07:21 +0100 by phpDocumentor 1.4.3