Skip to main content
Version: 2024.2

Working With Documents via PHP API

Pimcore provides the object orientated PHP API to work with Documents.

CRUD Operations

Create a New Document

To create a new document, you need to specify two mandatory attributes:

  • A unique key
  • A parent ID - ID of the parent document (document, folder and every other type)

You can set also every other value available in documents structure (settings, properties, children etc.).

Type of the document (page, folder, link, email, snippet etc.) The complete list can be obtained using: \Pimcore\Model\Document::getTypes() Every type has its own model, for example: a link document could be created by new \Pimcore\Model\Document\Link.

The example below, shows how to create simple page document via the PHP API.

$page = new \Pimcore\Model\Document\Page();
$page->setParentId(82); // id of a document or folder

// the optional parameter allows you to provide additional info
// currently supported:
// * versionNote: note added to the version (see version tab)
$page->save(["versionNote" => "my new version"]);

Now you can refresh the parent node of the newly created document in the admin interface (ID 82 in this case) and you'll see the newly created document.

Create document by APICreate document by APICreate document by API

Edit an Existing Document

If you'd like to get a document you can use the getById() or getByPath() method from the \Pimcore\Model\Document class.

Find below, the list of available methods for loading documents.

\Pimcore\Model\Document::getByIdint $id
\Pimcore\Model\Document::getByPathstring $path

The following code presents how to get the wysiwyg editable value of the document.

$document = \Pimcore\Model\Document::getById(4);
if($document) {
//the logic when the type of the document is page
/** @var \Pimcore\Model\Document\Page $document */

/** @var \Pimcore\Model\Document\Editable\Wysiwyg $wysiwygElement */
$wysiwygElement = $document->getEditable('content');


You've probably guessed that if you want to change value of a chosen editable or any other value, you can just set the value (by an available method) and after, save the document.

/** @var \Pimcore\Model\Document\Editable\Wysiwyg $wysiwygElement */
$wysiwygElement = $document->getEditable('content');
$wysiwygElement->setDataFromResource('<p>Lorem Ipsum is simply dummy text of the printing and typesetting.</p>');
$document->save(); //save changes in the document

Delete a Document

As simple or even simpler is deletion. Just load the document and use delete method available in \Pimcore\Model\Document.

$document = \Pimcore\Model\Document::getById(110);
if ($document) {

Document Listings


Let's assume that we have the following document tree structure:

Apitests children - previewApitests children - previewApitests children - preview

The code below retrieves all published documents with parentId = 82:

$listing = new \Pimcore\Model\Document\Listing(); 
$listing->setCondition("parentId = 82");
foreach($listing as $doc) {
// do whatever you like

If you'd like to get also all the unpublished documents, set the following flag: $listing->setUnpublished(true);.


setOrder()string (asc,desc)Set ascending or descending order type.
setOrderKey()stringChosen column name / names for as a order key. You can choose many order keys.
setLimit()intamount of collection results limit
setOffset()inta distance from beginning of the collection items
setCondition()stringYour own SQL condition like in the example above.


getTotalCount()Returns total number of selected rows.
getPaginatorAdapter()List implements \Iterator, you could use the list as a paginator.
getItems()int $offset, int $itemsCountPerPageas arguments you have to specify the limit of rows and the offset.
loadIdList()Returns complete array with id as a row.

If you want to know more about the paginator usage with lists, you should visit Working with Objects via PHP API part.

Advanced Example

$listing = new \Pimcore\Model\Document\Listing();
$listing->setCondition("`parentId` = 82")
->setOrderKey(['key', 'published'])


foreach($listing as $item) {
// ...

Alternatively, you can use the following static method to get a listing of documents:

//list all published children from the folder
/** @var \Pimcore\Model\Document\Listing $listing */
$listing = \Pimcore\Model\Document::getList([
'unpublished' => true,
'condition' => "`parentId` = 82",
'orderKey' => ['key', 'published'],
'order' => 'desc',
'offset' => 2,
'limit' => 2