[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @author   Neuman Vong [email protected]
   5   * @license  http://creativecommons.org/licenses/MIT/ MIT
   6   * @link     http://pear.php.net/package/Services_Twilio
   7   */
   8  
   9  /**
  10   * Abstraction of a list resource from the Twilio API.
  11   *
  12   * The list resource implements the `IteratorAggregate
  13   * <http://php.net/manual/en/class.iteratoraggregate.php>`_ and the `Countable
  14   * <http://php.net/manual/en/class.countable.php>`_ interfaces.
  15   *
  16   */
  17  abstract class Services_Twilio_ListResource extends Services_Twilio_Resource
  18      implements IteratorAggregate, Countable
  19  {
  20  
  21      public function __construct($client, $uri) {
  22          $name = $this->getResourceName(true);
  23          /*
  24           * By default trim the 's' from the end of the list name to get the
  25           * instance name (ex Accounts -> Account). This behavior can be
  26           * overridden by child classes if the rule doesn't work.
  27           */
  28          if (!isset($this->instance_name)) {
  29              $this->instance_name = "Services_Twilio_Rest_" . rtrim($name, 's');
  30          }
  31  
  32          parent::__construct($client, $uri);
  33      }
  34  
  35      /**
  36       * Gets a resource from this list.
  37       *
  38       * :param string $sid: The resource SID
  39       * :return: The resource
  40       * :rtype: :php:class:`InstanceResource <Services_Twilio_InstanceResource>`
  41       */
  42      public function get($sid) {
  43          $instance = new $this->instance_name(
  44              $this->client, $this->uri . "/$sid"
  45          );
  46          // XXX check if this is actually a sid in all cases.
  47          $instance->sid = $sid;
  48          return $instance;
  49      }
  50  
  51      /**
  52       * Construct an :php:class:`InstanceResource
  53       * <Services_Twilio_InstanceResource>` with the specified params.
  54       *
  55       * :param array $params: usually a JSON HTTP response from the API
  56       * :return: An instance with properties
  57       *      initialized to the values in the params array.
  58       * :rtype: :php:class:`InstanceResource <Services_Twilio_InstanceResource>`
  59       */
  60      public function getObjectFromJson($params, $idParam = "sid")
  61      {
  62          if (isset($params->{$idParam})) {
  63              $uri = $this->uri . "/" . $params->{$idParam};
  64          } else {
  65              $uri = $this->uri;
  66          }
  67          return new $this->instance_name($this->client, $uri, $params);
  68      }
  69  
  70      /**
  71       * Deletes a resource from this list.
  72       *
  73       * :param string $sid: The resource SID
  74       * :rtype: null
  75       */
  76      public function delete($sid, $params = array())
  77      {
  78          $this->client->deleteData($this->uri . '/' . $sid, $params);
  79      }
  80  
  81      /**
  82       * Create a resource on the list and then return its representation as an
  83       * InstanceResource.
  84       *
  85       * :param array $params: The parameters with which to create the resource
  86       *
  87       * :return: The created resource
  88       * :rtype: :php:class:`InstanceResource <Services_Twilio_InstanceResource>`
  89       */
  90      protected function _create($params)
  91      {
  92          $params = $this->client->createData($this->uri, $params);
  93          /* Some methods like verified caller ID don't return sids. */
  94          if (isset($params->sid)) {
  95              $resource_uri = $this->uri . '/' . $params->sid;
  96          } else {
  97              $resource_uri = $this->uri;
  98          }
  99          return new $this->instance_name($this->client, $resource_uri, $params);
 100      }
 101  
 102      /**
 103       * Returns a page of :php:class:`InstanceResources
 104       * <Services_Twilio_InstanceResource>` from this list.
 105       *
 106       * :param int    $page: The start page
 107       * :param int    $size: Number of items per page
 108       * :param array  $filters: Optional filters
 109       * :param string $deep_paging_uri: if provided, the $page and $size
 110       *      parameters will be ignored and this URI will be requested directly.
 111       *
 112       * :return: A page of resources
 113       * :rtype: :php:class:`Services_Twilio_Page`
 114       */
 115      public function getPage(
 116          $page = 0, $size = 50, $filters = array(), $deep_paging_uri = null
 117      ) {
 118          $list_name = $this->getResourceName();
 119          if ($deep_paging_uri !== null) {
 120              $page = $this->client->retrieveData($deep_paging_uri, array(), true);
 121          } else {
 122              $page = $this->client->retrieveData($this->uri, array(
 123                  'Page' => $page,
 124                  'PageSize' => $size,
 125              ) + $filters);
 126          }
 127  
 128          /* create a new PHP object for each json obj in the api response. */
 129          $page->$list_name = array_map(
 130              array($this, 'getObjectFromJson'),
 131              $page->$list_name
 132          );
 133          if (isset($page->next_page_uri)) {
 134              $next_page_uri = $page->next_page_uri;
 135          } else {
 136              $next_page_uri = null;
 137          }
 138          return new Services_Twilio_Page($page, $list_name, $next_page_uri);
 139      }
 140  
 141      /**
 142       * Get the total number of instances for this list.
 143       *
 144       * This will make one HTTP request to retrieve the total, every time this
 145       * method is called.
 146       *
 147       * If the total is not set, or an Exception was thrown, returns 0
 148       *
 149       * :return: The total number of instance members
 150       * :rtype: integer
 151       */
 152      public function count() {
 153          try {
 154              $page = $this->getPage(0, 1);
 155              return $page ? (int)$page->total : 0;
 156          } catch (Exception $e) {
 157              return 0;
 158          }
 159      }
 160  
 161  
 162      /**
 163       * Returns an iterable list of
 164       * :php:class:`instance resources <Services_Twilio_InstanceResource>`.
 165       *
 166       * :param int   $page: The start page
 167       * :param int   $size: Number of items per page
 168       * :param array $filters: Optional filters.
 169       *      The filter array can accept full datetimes when StartTime or DateCreated
 170       *      are used. Inequalities should be within the key portion of the array and
 171       *      multiple filter parameters can be combined for more specific searches.
 172       *
 173       *      .. code-block:: php
 174       *
 175       *          array('DateCreated>' => '2011-07-05 08:00:00', 'DateCreated<' => '2011-08-01')
 176       *
 177       *      .. code-block:: php
 178       *
 179       *          array('StartTime<' => '2011-07-05 08:00:00')
 180       *
 181       * :return: An iterator
 182       * :rtype: :php:class:`Services_Twilio_AutoPagingIterator`
 183       */
 184      public function getIterator(
 185          $page = 0, $size = 50, $filters = array()
 186      ) {
 187          return new Services_Twilio_AutoPagingIterator(
 188              array($this, 'getPageGenerator'), $page, $size, $filters
 189          );
 190      }
 191  
 192      /**
 193       * Retrieve a new page of API results, and update iterator parameters. This
 194       * function is called by the paging iterator to retrieve a new page and
 195       * shouldn't be called directly.
 196       */
 197      public function getPageGenerator(
 198          $page, $size, $filters = array(), $deep_paging_uri = null
 199      ) {
 200          return $this->getPage($page, $size, $filters, $deep_paging_uri);
 201      }
 202  }
 203