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.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 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.

External publication

Don't send a slow HTTP request directly to saving: this will hold user and transaction. In published write a small task in outbox with unique key service + document_id + revision. Web-runner will process it limited packages, will save attempts and allow you to repeat the error from the panel management.