ave-cms/help/en/hooks/documents.md

Document saving hooks

← To the section “Hooks and events”

The control panel, JSON API and system writer services use the same events. This is the main integration point for publishing in Telegram, Zen, CRM and others services.

Events

Name	When
content.document.saving	Before recording; the data can be changed or rejected.
content.document.persisted	After the write but before commit; only for a short transactional DB write.
content.document.saved	After a successful commit and snapshot build.
content.document.created	After creation.
content.document.updated	After the update.
content.document.published	On first publication or transition 0 → 1.
content.document.unpublished	During the transition 1 → 0.

They all receive App\Content\Documents\DocumentSaveEvent.

Available data

public static function beforeSave(DocumentSaveEvent $event)
{
    $title = $event->value('title');
    $code = $event->field('product_code');

    $event->setValue('title', trim((string) $title));
    $event->setField('product_code', strtoupper((string) $code));
}

Method	Destination
phase()	saving, persisted or saved.
operation()	create or update.
source()	For example, adminx or API writer.
documentId(), rubricId(), actorId()	Operation IDs.
isNew()	Is the document being created?
data(), value(), setValue()	System properties of the document.
fields(), field(), setField()	Field values ​​by ID or alias.
previous()	Previous state when updating.
snapshot()	The final JSON snapshot in after-events.
fail($message, $errors)	Before-save rejection.

Short names title, alias, status, published_at, expire_at, parent_id, template_id, breadcrumb_title, excerpt, tags, property and in_search are automatically mapped to document columns. Old name teaser is read as an alias for excerpt, but in the new code use excerpt.

Reject save

public static function validateCertificate(DocumentSaveEvent $event)
{
    if ($event->rubricId() !== 12 || trim((string) $event->field('certificate')) !== '') {
        return;
    }

    $event->fail('Документ не сохранён', array(
        'fields[certificate]' => 'Укажите номер сертификата',
    ));
}

fail() is only taken into account before the entry. Writer turns it into a controlled error and does not save partial data.

After events are executed after commit. Their exceptions are logged and not roll back an already saved document. Therefore the handler must be idempotent: calling again does not create a second post, payment or task.

content.document.persisted is the exception: it runs inside the transaction. An exception rolls the document back. Do not send HTTP requests or email from this hook; only a short write to the same database is allowed. The built-in Reliable events module uses this hook automatically.

External publication

Do not send slow HTTP requests from document hooks. Install Reliable events, subscribe to content.document.published, and enable its Scheduler task. The module writes the event atomically with the document and delivers it later in controlled batches.