Creating and updating content in code #

This page is for application creators who write content from code: imports, synchronizations, forms that create objects, migrations. The kernel's eZContentFunctions (kernel/classes/ezcontentfunctions.php) creates and publishes in one call, with the same operation (and triggers) as the editor.

Since Exponential 6.0.15 there is a second way that is often simpler: expContentWriter takes rich text as HTML and files as public web addresses, and tells you whether the content was published, is waiting for a workflow or was refused and why (From plain values: expContentWriter).

Contents #

1. Creating and publishing
2. Updating
3. Values for each datatype
4. Idempotent imports with remote IDs
5. Moving, hiding, removing
6. Large operations
7. From plain values: expContentWriter

Creating and publishing #

$object = eZContentFunctions::createAndPublishObject( array(
    'creator_id'       => $userID,
    'class_identifier' => 'article',
    'parent_node_id'   => $parentNodeID,
    'remote_id'        => 'feed-item-' . $externalID,
    'attributes'       => array(
        'title' => 'A new article',
        'intro' => $introXml,
        'body'  => $bodyXml ) ) );

if ( !$object instanceof eZContentObject )
    throw new RuntimeException( 'Could not create the article' );

Attribute values are given in their fromString() form. Publishing runs the content/publish operation, so workflows on its triggers run too, and caches and the search index are updated.

Updating #

eZContentFunctions::updateAndPublishObject( $object, array(
    'attributes' => array( 'title' => 'A better title' ) ) );

A new version is created and published; the previous one becomes archived, like an editor's edit.

Values for each datatype #

The exact format of each is in its datatype class's fromString() in kernel/classes/datatypes/<name>/; read it before importing a datatype for the first time.

Idempotent imports with remote IDs #

Give imported objects a remote ID built from the source's ID. On the next run, update instead of create:

$remoteID = 'feed-item-' . $externalID;
$existing = eZContentObject::fetchByRemoteID( $remoteID );
if ( $existing )
    eZContentFunctions::updateAndPublishObject( $existing, array( 'attributes' => $attributes ) );
else
    eZContentFunctions::createAndPublishObject( array( 'remote_id' => $remoteID ) + $params );

Running an import twice must not create duplicates.

Moving, hiding, removing #

Use the kernel operations rather than SQL: eZContentObjectTreeNodeOperations::move(), eZContentOperationCollection for hide and reveal, eZContentObjectTreeNode::removeSubtrees() for removal (to the trash or not). They keep URL aliases, caches and the search index right.

Large operations #

Thousands of objects belong in a background process: a command run from cron, a queue job (Queues with expqueue), or the kernel's content jobs for removes, copies and moves of large subtrees (Content jobs). Commit in batches, clear eZContentObject::clearCache() between batches, and log progress.

From plain values: expContentWriter #

<?php
$result = expContentWriter::create( array(
    'parentNodeID'    => $parentNodeID,
    'classIdentifier' => 'article',
    'languageLocale'  => 'eng-US',
    'remoteID'        => 'myapp-article-' . $externalID,
    'attributes'      => array(
        'title' => $title,
        'intro' => '<p>' . htmlspecialchars( $teaser ) . '</p>',            // rich text as HTML
        'image' => 'https://cdn.example.org/a/' . $externalID . '.jpg|' . $title, // downloaded, with its alternative text
    ),
) );
if ( $result['status'] === 'invalid' || $result['status'] === 'failed' )
    eZDebug::writeError( $result['message'], 'myapp import' );

if ( $result['object'] instanceof eZContentObject )
    $result = expContentWriter::update( $result['object'], array( 'title' => $newTitle ), 'eng-US' ); // a new version

update() changes only the attributes given and publishes a new version; a language the object does not have yet adds a translation. remove( $object, true ) moves the object to the trash. The writer does not check permissions; check them first when the code acts for a user. Everything about it: Writing content from PHP with expContentWriter. The REST API uses the same writer, so an app can update content over HTTP (REST API v1 and v2 for applications).

Related pages #

• The content API in PHP
• Content from plain values: expContentWriter
• CLI scripts with eZScript
• Workflows, triggers and events
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.