ListResource.php 6.6 KB

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