Pagination

Certain API operations return lists of objects. When the number of objects in the list is large, the API will paginate the results.

Each list method that pages through its results with a cursor has a page counterpart that fetches one page at a time: Folder::listFor() has Folder::listForPage(), User::all() has User::listPage(), and so on. A page method takes the same parameters and options as its list method and returns a \Files\Page.

Automatic Pagination

autoPagingIterator() yields every item from a page onward. It requests each following page only when the loop reaches it, so a break sends no further requests. Pages can be empty and still be followed by more items; the iterator keeps going until the API reports the last page.

Example Request

try {
  $files = \Files\Model\Folder::listForPage($path, ['per_page' => 1000])->autoPagingIterator();
  foreach ($files as $file) {
    // Operate on $file
  }
} catch (\Files\Exception\NotAuthenticatedException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\Exception\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Manual Pagination

A foreach over a page visits only the items on that page. nextPage() fetches the next page and returns null, without a request, once hasNextPage() is false. A page never changes after it is fetched, so if fetching the next page fails, the current page is still usable and nextPage() can be called again. If the API returns a cursor that already led to that page or an earlier one, nextPage() raises \Files\Exception\ApiBadResponseException instead of repeating pages.

Every page is requested with the parameters and options given to the page method, without an added page number. Settings those options do not override, such as the API key set with \Files\Files::setApiKey(), are read as each page is requested.

Example Request

try {
  $page = \Files\Model\Folder::listForPage($path, ['per_page' => 1000]);
  while ($page !== null) {
    foreach ($page as $file) {
      // Operate on $file
    }
    $page = $page->nextPage();
  }
} catch (\Files\Exception\NotAuthenticatedException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\Exception\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Resuming and Restarting

getNextCursor() returns the opaque cursor for the next page, or null on the last page, where there is nothing to continue. Pass a cursor back unchanged, as the cursor parameter of the same page method, to continue from there later, for example in another process.

restart() fetches the first page again with the original parameters and options, without any cursor.

Example Request

try {
  $page = \Files\Model\Folder::listForPage($path, ['per_page' => 1000]);
  $cursor = $page->getNextCursor();
  
  // Later: continue with the page after $page, if there is one
  if ($cursor !== null) {
    $next = \Files\Model\Folder::listForPage($path, ['per_page' => 1000, 'cursor' => $cursor]);
  }
  
  // At any time: start over from the first page
  $first = $page->restart();
} catch (\Files\Exception\NotAuthenticatedException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\Exception\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}

Lists as Arrays

The list methods themselves return an array. With \Files\Files::$autoPaginate set to true, the default, they fetch every page before returning, holding the entire list in memory. With false, they return only the first page. Page methods are not affected by this setting.

A list method stops with \Files\Exception\ApiBadResponseException when a page is not a list, or when the API returns a cursor the list already sent, instead of requesting pages without end.

Example Request

// true by default
\Files\Files::$autoPaginate = true;

try {
  $files = \Files\Model\Folder::listFor($path, [
    'search' => "some-partial-filename"
  ]);
  foreach ($files as $file) {
    // Operate on $file
  }
} catch (\Files\Exception\NotAuthenticatedException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
} catch (\Files\Exception\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ', $e->getMessage(), "\n";
}