Pages

The $pages API variable enables loading and manipulation of Page objects, to and from the database.

Manages Page instances, providing find, load, save and delete capabilities. The implementation for most of the methods in this class are delegated to other classes (helpers) but this class provides the common and hookable interface to all of them. The $pages API variable is the most used object in the ProcessWire API. The most commonly used API methods include:

$pages->find($selector); Finds and returns multiple pages.
$pages->get($selector); Finds a single page with no exclusions.
$pages->save($page); Saves given page.

Click any linked item for full usage details and examples. Hookable methods are indicated with the icon. In addition to those shown below, the Pages class also inherits all the methods and properties of: Wire.

Retrieve

Name	Return	Summary
$pages->count() $pages->count() $pages->count($selector = '', $options = [])	`int`	Count and return how many pages will match the given selector.
$pages->find() $pages->find($selector) $pages->find($selector, $options = [])	`PageArray` `array`	Given a Selector string, return the Page objects that match in a PageArray.
$pages->findIDs() $pages->findIDs($selector) $pages->findIDs($selector, $options = [])	`array`	Like find() except returns array of IDs rather than Page objects
$pages->findMany() $pages->findMany($selector) $pages->findMany($selector, array $options = [])	`PageArray`	Like find(), but with “lazy loading” to support giant result sets without running out of memory.
$pages->findOne() $pages->findOne($selector) $pages->findOne($selector, $options = [])	`Page` `NullPage`	Like find() but returns only the first match as a Page object (not PageArray).
$pages->findRaw() $pages->findRaw($selector) $pages->findRaw($selector, $field = '', array $options = [])	`array`	Find pages and return raw data from them in a PHP array
$pages->get() $pages->get($selector) $pages->get($selector, array $options = [])	`Page` `NullPage`	Returns the first page matching the given selector with no exclusions
$pages->getByIDs() $pages->getByIDs($ids) $pages->getByIDs($ids, array $options = [])	`PageArray` `Page`	Given array or CSV string of Page IDs, return a PageArray
$pages->getFresh() $pages->getFresh($selectorOrPage) $pages->getFresh($selectorOrPage, array $options = [])	`Page` `NullPage`	Get a fresh, non-cached copy of a Page from the database
$pages->getRaw() $pages->getRaw($selector) $pages->getRaw($selector, $field = '', array $options = [])	`array`	Get single page and return raw data in an associative array
$pages->has() $pages->has($selector) $pages->has($selector, bool $verbose = false)	`array` `int`	Is there any page that matches the given $selector in the system? (with no exclusions)

Save

Name	Return	Summary
$pages->save() $pages->save(Page $page) $pages->save(Page $page, array $options = [])	`bool`	Save a page object and its fields to database.
$pages->saveField() $pages->saveField(Page $page, $field) $pages->saveField(Page $page, $field, $options = [])	`bool`	Save only a field from the given page
$pages->saveFields() $pages->saveFields(Page $page, $fields) $pages->saveFields(Page $page, $fields, array $options = [])	`array`	Save multiple named fields from given page
$pages->touch() $pages->touch($pages) $pages->touch($pages, $options = null, string $type = 'modified')	`bool`	Update page modification time to now (or the given modification time)

Add

Name	Return	Summary
$pages->add() $pages->add($template, $parent) $pages->add($template, $parent, string $name = '', array $values = [])	`Page`	Add a new page using the given template and parent
$pages->clone() $pages->clone(Page $page) $pages->clone(Page $page, $parent = null, bool $recursive = true, $options = [])	`Page` `NullPage`	Clone entire page and return it
$pages->new() $pages->new() $pages->new($selector = '')	`Page`	Create a new Page populated from selector string or array and save to database
$pages->newPage() $pages->newPage() $pages->newPage($options = [])	`Page`	Return a new Page object without saving it to the database

Trash

Name	Return	Summary
$pages->delete() $pages->delete(Page $page) $pages->delete(Page $page, $recursive = false, array $options = [])	`bool` `int`	Permanently delete a page, its fields and assets.
$pages->emptyTrash() $pages->emptyTrash() $pages->emptyTrash(array $options = [])	`int` `array`	Delete all pages in the trash
$pages->restore() $pages->restore(Page $page) $pages->restore(Page $page, bool $save = true)	`bool`	Restore a page in the trash back to its original location and state
$pages->trash() $pages->trash(Page $page) $pages->trash(Page $page, bool $save = true)	`bool`	Move a page to the trash

Move

Name	Return	Summary
$pages->insertAfter() $pages->insertAfter(Page $page, Page $afterPage) $pages->insertAfter(Page $page, Page $afterPage)	None	Sort/move one page after another (for manually sorted pages)
$pages->insertBefore() $pages->insertBefore(Page $page, Page $beforePage) $pages->insertBefore(Page $page, Page $beforePage)	None	Sort/move one page above another (for manually sorted pages)
$pages->sort() $pages->sort(Page $page) $pages->sort(Page $page, $value = false)	`int`	Set the “sort” value for given $page while adjusting siblings, or re-build sort for its children

Advanced

Name	Return	Summary
$pages->findJoin() $pages->findJoin($selector, $joinFields) $pages->findJoin($selector, $joinFields, array $options = [])	`PageArray`	Find pages and specify which fields to join (overriding configured autojoin settings)
$pages->getById() $pages->getById($_ids) $pages->getById($_ids, $template = null, $parent_id = null)	`PageArray` `Page`	Given an array or CSV string of Page IDs, return a PageArray (internal API)
$pages->getByPath() $pages->getByPath(string $path) $pages->getByPath(string $path, $options = [])	`Page` `int`	Get a page by its path, similar to $pages->get('/path/to/page/') but with more options
$pages->getID() $pages->getID($selector) $pages->getID($selector, $options = [])	`int` `array`	Get one ID of page matching given selector with no exclusions, like get() but returns ID rather than a Page
$pages->getInfoByPath() $pages->getInfoByPath(string $path) $pages->getInfoByPath(string $path, array $options = [])	`array`	Get verbose array of info about a given page path
$pages->getOneById() $pages->getOneById(int $id) $pages->getOneById(int $id, array $options = [])	`Page` `NullPage`	Get one page by ID
$pages->getPath() $pages->getPath($id) $pages->getPath($id, $options = [])	`string`	Given an ID, return a path to a page, without loading the actual page
$pages->of() $pages->of() $pages->of($of = null)	`bool`	Get or set the current output formatting state

Cache

Name	Return	Summary
$pages->getCache() $pages->getCache() $pages->getCache($id = null)	`Page` `array` `null`	Given a Page ID, return it if it's cached, or NULL of it's not.
$pages->uncache() $pages->uncache() $pages->uncache($page = null, array $options = [])	`int`	Remove the given page(s) from the cache, or uncache all by omitting $page argument
$pages->uncacheAll() $pages->uncacheAll() $pages->uncacheAll($page = null, array $options = [])	`int`	Remove all pages from the cache (to clear memory)

Helpers

Methods that point to dedicated Pages helper classes. Use methods from $pages rather than the helpers when there is crossover.

Name	Return	Summary
$pages->cacher() $pages->cacher() $pages->cacher()	`PagesLoaderCache`	Get PagesLoaderCache instance which provides methods for caching pages in memory
$pages->editor() $pages->editor() $pages->editor()	`PagesEditor`	Get PagesEditor instance which provides methods for saving pages to the database
$pages->loader() $pages->loader() $pages->loader()	`PagesLoader`	Get PagesLoader instance which provides methods for finding and loading pages
$pages->names() $pages->names() $pages->names()	`PagesNames`	Get PagesNames instance which provides API methods specific to generating and modifying page names
$pages->parents() $pages->parents() $pages->parents()	`PagesParents`	Get PagesParents instance which provides methods for managing parent/child relationships in the pages_parents table
$pages->pathFinder() $pages->pathFinder() $pages->pathFinder()	`PagesPathFinder`	Get the PagesPathFinder instance which provides methods for finding pages by paths
$pages->porter() $pages->porter() $pages->porter()	`PagesExportImport`	Get new instance of PagesExportImport for exporting and importing pages
$pages->raw() $pages->raw() $pages->raw()	`PagesRaw`	Get the PagesRaw instance which provides methods for findind and loading raw pages data
$pages->request() $pages->request() $pages->request()	`PagesRequest`	Get the PagesRequest instance which provides methods for identifying and loading page from current request URL
$pages->trasher() $pages->trasher() $pages->trasher()	`PagesTrash`	Get PagesTrash instance which provides methods for managing the Pages trash

Save hooks

Methods called automatically when a page is saved. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->saveFieldReady() $pages->saveFieldReady(Page $page, Field $field) $pages->saveFieldReady(Page $page, Field $field)	None	Hook called when Pages::saveField is ready to execute
$pages->savePageOrFieldReady() $pages->savePageOrFieldReady(Page $page) $pages->savePageOrFieldReady(Page $page, string $fieldName = '')	None	Hook called when either of Pages::save or Pages::saveField is ready to execute
$pages->saveReady() $pages->saveReady(Page $page) $pages->saveReady(Page $page)	`array`	Hook called just before a page is saved
$pages->saved() $pages->saved(Page $page) $pages->saved(Page $page, array $changes = [], array $values = [])	None	Hook called after a page is successfully saved
$pages->savedField() $pages->savedField(Page $page, Field $field) $pages->savedField(Page $page, Field $field)	None	Hook called after Pages::saveField successfully executes
$pages->savedPageOrField() $pages->savedPageOrField(Page $page) $pages->savedPageOrField(Page $page, array $changes = [])	None	Hook called after either of Pages::save or Pages::saveField successfully executes
$pages->templateChanged() $pages->templateChanged(Page $page) $pages->templateChanged(Page $page)	None	Hook called when a page's template has been changed

Add hooks

Methods called automatically when a page is added. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->addReady() $pages->addReady(Page $page) $pages->addReady(Page $page)	None	Hook called when a new page is about to be added and saved to the database
$pages->added() $pages->added(Page $page) $pages->added(Page $page)	None	Hook called after a new page has been added
$pages->cloneReady() $pages->cloneReady(Page $page, Page $copy) $pages->cloneReady(Page $page, Page $copy)	None	Hook called when a page is about to be cloned, but before data has been touched
$pages->cloned() $pages->cloned(Page $page, Page $copy) $pages->cloned(Page $page, Page $copy)	None	Hook called when a page has been cloned

Move hooks

Methods called automatically when a page is moved, sorted or renamed. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->moveReady() $pages->moveReady(Page $page) $pages->moveReady(Page $page)	None	Hook called when a page is about to be moved to another parent
$pages->moved() $pages->moved(Page $page) $pages->moved(Page $page)	None	Hook called when a page has been moved from one parent to another
$pages->renameReady() $pages->renameReady(Page $page) $pages->renameReady(Page $page)	None	Hook called when a page is about to be renamed i.e. had its name field change)
$pages->renamed() $pages->renamed(Page $page) $pages->renamed(Page $page)	None	Hook called when a page has been renamed (i.e. had its name field change)
$pages->sorted() $pages->sorted(Page $page) $pages->sorted(Page $page, bool $children = false, int $total = 0)	None	Hook called after a page has been sorted, or had its children re-sorted

Trash hooks

Methods called automatically when a page is trashed or restored. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->restoreReady() $pages->restoreReady(Page $page) $pages->restoreReady(Page $page)	None	Hook called when a page is about to be moved OUT of the trash (restored)
$pages->restored() $pages->restored(Page $page) $pages->restored(Page $page)	None	Hook called when a page has been moved OUT of the trash (restored)
$pages->trashReady() $pages->trashReady(Page $page) $pages->trashReady(Page $page)	None	Hook called when a Page is about to be trashed
$pages->trashed() $pages->trashed(Page $page) $pages->trashed(Page $page)	None	Hook called when a page has been moved to the trash

Delete hooks

Methods called automatically when a page is deleted. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->deleteBranchReady() $pages->deleteBranchReady(Page $page, array $options) $pages->deleteBranchReady(Page $page, array $options)	None	Hook called before a branch of pages is about to be deleted, called on root page of branch only
$pages->deleteReady() $pages->deleteReady(Page $page) $pages->deleteReady(Page $page, array $options = [])	None	Hook called when a page is about to be deleted, but before data has been touched
$pages->deleted() $pages->deleted(Page $page) $pages->deleted(Page $page, array $options = [])	None	Hook called after a page and its data have been deleted
$pages->deletedBranch() $pages->deletedBranch(Page $page, array $options, int $numDeleted) $pages->deletedBranch(Page $page, array $options, int $numDeleted)	None	Hook called after a a branch of pages has been deleted, called on root page of branch only

Status hooks

Methods called automatically when a page status changes. You can hook these methods but should not call them directly.

Name	Return	Summary
$pages->publishReady() $pages->publishReady(Page $page) $pages->publishReady(Page $page)	None	Hook called right before an unpublished page is published and saved
$pages->published() $pages->published(Page $page) $pages->published(Page $page)	None	Hook called after an unpublished page has just been published
$pages->statusChangeReady() $pages->statusChangeReady(Page $page) $pages->statusChangeReady(Page $page)	None	Hook called when a page's status is about to be changed and saved
$pages->statusChanged() $pages->statusChanged(Page $page) $pages->statusChanged(Page $page)	None	Hook called when a page status has been changed and saved
$pages->unpublishReady() $pages->unpublishReady(Page $page) $pages->unpublishReady(Page $page)	None	Hook called right before a published page is unpublished and saved
$pages->unpublished() $pages->unpublished(Page $page) $pages->unpublished(Page $page)	None	Hook called after published page has just been unpublished

Find hooks

Method called automatically when pages are found. You can hook this method but should not call it directly.

Name	Return	Summary
$pages->found() $pages->found(PageArray $pages, array $details) $pages->found(PageArray $pages, array $details)	None	Hook called at the end of a $pages->find(), includes extra info not seen in the resulting PageArray

Additional methods and properties

In addition to the methods and properties above, Pages also inherits the methods and properties of these classes:

Wire

API reference based on ProcessWire core version 3.0.252