Stack.PHP
A simple and easy to use PHP library for the Stack Exchange API.
Public Member Functions | Protected Member Functions
PagedResponse Class Reference

An object capable of requesting paged data sequentially. More...

Inheritance diagram for PagedResponse:
PagedSiteResponse

List of all members.

Public Member Functions

 __construct ($base_url, $return_object)
 Constructor for a response.
 Fetch ($fetch_next=TRUE)
 Returns the next item in the set.
 Reset ($reset_all=TRUE)
 Resets the internal index.
 Page ($page=null, $include_total=FALSE)
 Fetches the specified page and resets the index.
 Pagesize ($pagesize)
 Sets the pagesize to the specified value.
 Total ($all_pages=TRUE)
 Returns the total number of items.

Protected Member Functions

 RetrieveDataFromURL ($include_total)
 Retrieves the data from the URL and verifies the type of items returned.

Detailed Description

An object capable of requesting paged data sequentially.

This class is returned by a call to PagedRequest::Exec() and provides a means of stepping through the items returned from your request. By default, additional pages are requested and returned behind the scenes to provide a seamless stream of items.

You fetch the next item in the sequence using PagedResponse::Fetch() which returns FALSE when no more items are available. This class is also aware of what filters need to be used to obtain the desired information. For example, to call PagedResponse::Total(), this class needs to have either received a reply containing the total number of items or it will then issue an appropriate request to obtain the information.


Constructor & Destructor Documentation

PagedResponse::__construct ( base_url,
return_object 
)

Constructor for a response.

Parameters:
$base_urlan instance of the URL class
$return_objectthe name of the object the items will be returned in

Member Function Documentation

PagedResponse::Fetch ( fetch_next = TRUE)

Returns the next item in the set.

Parameters:
$fetch_nextwhether to fetch the next page if there are no more items in the current page
Returns:
the next item in the set or FALSE if none

Reimplemented in PagedSiteResponse.

PagedResponse::Page ( page = null,
include_total = FALSE 
)

Fetches the specified page and resets the index.

Parameters:
$pagethe page number to fetch
$include_totalwhether this filter needs to include total number of items
Returns:
the current instance

Note: $page defaults to either the first page or the most recently specified page

PagedResponse::Pagesize ( pagesize)

Sets the pagesize to the specified value.

Parameters:
$pagesizethe number of items that each page should contain
Returns:
the current instance

Note: this method should not be called after the first request is made as it will invalidate the internal index.

PagedResponse::Reset ( reset_all = TRUE)

Resets the internal index.

Parameters:
$reset_allwhether to reset the index to the beginning of all pages
PagedResponse::RetrieveDataFromURL ( include_total) [protected]

Retrieves the data from the URL and verifies the type of items returned.

Parameters:
$include_totalwhether this filter needs to include total number of items
PagedResponse::Total ( all_pages = TRUE)

Returns the total number of items.

Parameters:
$all_pagesTRUE to include the total of all pages
Returns:
the total number of items

This method's behavior depends heavily on its arguments and the current filter. If the filter provides 'total' in the response, then this method will return that value by default. If not, then a separate request will be made to retrieve that data using a custom filter.

If you merely want the total number of items in the current page, then simply use FALSE for $all_pages. If no data has been fetched yet, this method will fetch the default page (likely the first).

Note that you do not need access to 'total' to simply enumerate all items across all pages. Use code like this:

while($item = $response->Fetch())

This will continue to fetch the next page even if 'total' is not returned in the response.


The documentation for this class was generated from the following file:
 All Classes Functions Variables