Edit on GitHub

Event API and Event Manager

General

Pimcore provides an extensive number of events that are fired during execution of Pimcore functions. These events can be used to hook into many Pimcore functions such as saving an object, asset or document and can be used to change or extend the default behavior of Pimcore.

The most common use-case for events is using them in a plugin, but of course you can use them also anywhere in your code or when hooking into the startup process.

You can attach a handler at any time in your code by using the following code:

\Pimcore::getEventManager()->attach("object.postAdd", function (\Zend_EventManager_Event $e) {
    $object = $e->getTarget();
    $object->getId();
    // ...
});

The Pimcore event API is based on the ZF Event Manager. Click here to learn more about attaching listeners to an event.

IMPORTANT INFO
Pimcore::getEventManager() returns an instance of Zend_EventManager_EventManager and therefore it provides the full set of functionalities that the ZF provides. For details have a look at http://framework.zend.com/manual/1.12/de/zend.event-manager.event-manager.html

Examples

The following example shows how to register events for assets, documents and objects where the event-handler is in a custom class.

<?php
namespace Website\Custom;
  
use Pimcore\Model;
class Extension {
     
    public function handleCreate (\Zend_EventManager_Event $e) {
        $element = $e->getTarget();
        if($element instanceof Model\Asset) {
            // do something with the asset
        } else if ($element instanceof Model\Document) {
            // do something with the document
        } else if ($element instanceof Model\Object\AbstractObject) {
            // do something with the object
        }
    }
     
    public function handleDelete(\Zend_EventManager_Event $e) {
        $element = $e->getTarget();
        // do something with the element
    }
}
$extension = new Website_Custom_Extension();
foreach (["asset","object","document"] as $type) {
    Pimcore::getEventManager()->attach($type . ".postAdd", [$extension, "handleCreate"]);
    Pimcore::getEventManager()->attach($type . ".postDelete", [$extension, "handleDelete"]);
}

The following example shows how to deal with event parameters and a static callback method.

<?php
namespace Website\Auth;
class Handler {
     
    public static function logout (\Zend_EventManager_Event $e) {
        $user = $e->getParam("user");
        // user is now an instance of User
         
        // do something with the user
        Logger::info("User with ID " . $user->getId() . " left the pimcore admin interface");
    }
}
\Pimcore::getEventManager()->attach("admin.login.logout", ["\Website\Auth\Handler", "logout"]);

This example show how to use an anonymous callback and a specific priority (87)

<?php
$myControllerPlugin = new \Website\Controller\Plugin\MyCustomPlugin();
$myControllerPlugin->someMethod();
 
\Pimcore::getEventManager()->attach("system.startup", function (\Zend_EventManager_Event $e) use ($myControllerPlugin) {
    $frontController = $e->getTarget();
    $frontController->registerPlugin($myControllerPlugin);
}, 87);

attach multiple events

\Pimcore::getEventManager()->attach(["object.postAdd","object.postUpdate"], function (\Zend_EventManager_Event $e) {
    $object = $e->getTarget();
    $object->getId();
    // ...
});

Available Events

System / General

Name	Target	Parameters	Description
`system.startup`	`Zend_Controller_Front`		This event is fired on startup, just before the MVC dispatch starts.
`system.shutdown`		-	This event is fired on shutdown (register_shutdown_function)
`system.maintenance`	`Pimcore\Model\Schedule\Manager\Procedural` or `Pimcore\Model\Schedule\Manager\Daemon`	-	Use this event to register your own maintenance jobs, this event is triggered just before the jobs are executed
`system.console.init`	`Pimcore\Console\Application`		See Console / CLI
`system.di.init`	`DI\ContainerBuilder`		Fires when the DI is built
`system.maintenance.activate`			This event is fired on maintenance mode activation
`system.maintenance.deactivate`			This event is fired on maintenance mode deactivation
`system.cache.clearOutputCache`			This event is fired on Output Cache clear
`system.cache.clear`			This event is fired on Cache clear
`system.cache.clearTemporaryFiles`			This event is fired on Temporary Files clear
`system.service.preGetValidKey`		(string) $key, (string) $type	Can be used to enforce your own key/filename policies for assets, documents and objects. To modify the key, just return the modified key in your callback function.

Document

Name	Target	Parameters	Description
`document.preAdd`	`Pimcore\Model\Document`	-
`document.postAdd`	`Pimcore\Model\Document`	-
`document.preUpdate`	`Pimcore\Model\Document`	(bool) `saveVersionOnly`	saveVersionOnly is set if method saveVersion() was called instead of save()
`document.postUpdate`	`Pimcore\Model\Document`	(bool) `saveVersionOnly`	saveVersionOnly is set if method saveVersion() was called instead of save()
`document.preDelete`	`Pimcore\Model\Document`	-
`document.postDelete`	`Pimcore\Model\Document`	-
`document.print.prePdfGeneration`	`Pimcore\Model\Document`	`Pimcore\Web2Print\Processor\{ProcessorName} processor`	processor contains the processor object used to generate the PDF
`document.print.postPdfGeneration`	`Pimcore\Model\Document`	(string) `filename`, (string) `pdf`	filename contains the filename of the generated pdf on filesystem, pdf contains generated pdf as string
`document.print.processor.modifyProcessingOptions`	Processor	(array)	modfiy the processing options for the adapter (displayed in the pimcore admin interface)
`document.print.processor.modifyConfig`	Processor	(array)	modfify the configuration which is passed to processor
`document.postCopy`	`Pimcore\Model\Document`	`Pimcore\Model\Document base_element`	base_element contains the base document used in copying process

Object

Name	Target	Parameters	Description
`object.preAdd`	`Pimcore\Model\Object\AbstractObject`	-
`object.postAdd`	`Pimcore\Model\Object\AbstractObject`	-
`object.preUpdate`	`Pimcore\Model\Object\AbstractObject`	(bool) saveVersionOnly	saveVersionOnly is set if method saveVersion() was called instead of save()
`object.postUpdate`	`Pimcore\Model\Object\AbstractObject`	(bool) saveVersionOnly	saveVersionOnly is set if method saveVersion() was called instead of save()
`object.preDelete`	`Pimcore\Model\Object\AbstractObject`	-
`object.postDelete`	`Pimcore\Model\Object\AbstractObject`	-
`object.postCopy`	`Pimcore\Model\Object\AbstractObject`	`Pimcore\Model\Object\AbstractObject base_element`	base_element contains the base object used in copying process

Asset

Name	Target	Parameters	Description
`asset.preAdd`	`Pimcore\Model\Asset`	-
`asset.postAdd`	`Pimcore\Model\Asset`	-
`asset.preUpdate`	`Pimcore\Model\Asset`	(bool) `saveVersionOnly`	saveVersionOnly is set if method saveVersion() was called instead of save()
`asset.postUpdate`	`Pimcore\Model\Asset`	(bool) `saveVersionOnly`	saveVersionOnly is set if method saveVersion() was called instead of save()
`asset.preDelete`	`Pimcore\Model\Asset`	-
`asset.postDelete`	`Pimcore\Model\Asset`	-
`asset.image.thumbnail`	`Pimcore\Model\Asset\Image\Thumbnail`	(bool) `deferred`, (bool) `generated`	fires after the thumbnail was created
`asset.video.image-thumbnail`	`Pimcore\Model\Asset\Video\ImageThumbnail`	(bool) `deferred`, (bool) `generated`	fires after the image thumbnail was created
`asset.document.image-thumbnail`	`Pimcore\Model\Asset\Document\ImageThumbnail`	(bool) `deferred`, (bool) `generated`	fires after the image thumbnail was created
`asset.postCopy`	`Pimcore\Model\Asset`	`Pimcore\Model\Asset base_element`	base_element contains the base asset used in copying process

Elements

Name	Target	Parameters	Description
`element.note.postAdd`	`Pimcore\Model\Element\Note`	-	Fired when a note was added to an object/asset/document

Object Class

Name	Target	Parameters
`object.class.preAdd`	`Pimcore\Model\Object\ClassDefinition`	-
`object.class.postAdd`	`Pimcore\Model\Object\ClassDefinition`	-
`object.class.preUpdate`	`Pimcore\Model\Object\ClassDefinition`	-
`object.class.postUpdate`	`Pimcore\Model\Object\ClassDefinition`	-
`object.class.preDelete`	`Pimcore\Model\Object\ClassDefinition`	-
`object.class.postDelete`	`Pimcore\Model\Object\ClassDefinition`	-

Object KeyValue Group Configuration

Name	Target	Parameters
`object.keyValue.groupConfig.preAdd`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-
`object.keyValue.groupConfig.postAdd`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-
`object.keyValue.groupConfig.preUpdate`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-
`object.keyValue.groupConfig.postUpdate`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-
`object.keyValue.groupConfig.preDelete`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-
`object.keyValue.groupConfig.postDelete`	`Pimcore\Model\Object\KeyValue\GroupConfig`	-

Object KeyValue Key Configuration

Name	Target	Parameters
`object.keyValue.keyConfig.preAdd`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-
`object.keyValue.keyConfig.postAdd`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-
`object.keyValue.keyConfig.preUpdate`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-
`object.keyValue.keyConfig.postUpdate`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-
`object.keyValue.keyConfig.preDelete`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-
`object.keyValue.keyConfig.postDelete`	`Pimcore\Model\Object\KeyValue\KeyConfig`	-

Object Classification Store Collection Configuration

Name	Target	Parameters
`object.classificationstore.collectionConfig.preAdd`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-
`object.classificationstore.collectionConfig.postAdd`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-
`object.classificationstore.collectionConfig.preUpdate`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-
`object.classificationstore.collectionConfig.postUpdate`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-
`object.classificationstore.collectionConfig.preDelete`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-
`object.classificationstore.collectionConfig.postDelete`	`Pimcore\Model\Object\Classificationstore\CollectionConfig`	-

Object Classification Store Group Configuration

Name	Target	Parameters
`object.classificationstore.groupConfig.preAdd`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-
`object.classificationstore.groupConfig.postAdd`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-
`object.classificationstore.groupConfig.preUpdate`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-
`object.classificationstore.groupConfig.postUpdate`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-
`object.classificationstore.groupConfig.preDelete`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-
`object.classificationstore.groupConfig.postDelete`	`Pimcore\Model\Object\Classificationstore\GroupConfig`	-

Object Classification Store Key Configuration

Name	Target	Parameters
`object.classificationstore.keyConfig.preAdd`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-
`object.classificationstore.keyConfig.postAdd`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-
`object.classificationstore.keyConfig.preUpdate`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-
`object.classificationstore.keyConfig.postUpdate`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-
`object.classificationstore.keyConfig.preDelete`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-
`object.classificationstore.keyConfig.postDelete`	`Pimcore\Model\Object\Classificationstore\KeyConfig`	-

Versions

Name	Target	Parameters
`version.preSave`	`Pimcore\Model\Element\AbstractElement`	-
`version.postSave`	`Pimcore\Model\Element\AbstractElement`	-
`version.preDelete`	`Pimcore\Model\Element\AbstractElement`	-
`version.postDelete`	`Pimcore\Model\Element\AbstractElement`	-

Search Backend

Name	Target	Parameters	Description
`search.backend.preSave`	`Pimcore\Model\Search\Backend\Data`	-
`search.backend.postSave`	`Pimcore\Model\Search\Backend\Data`	-

Search Dialogs

Various events that can be used to manipulate a search request.

Name	Target	Parameters	Description
`admin.search.list.beforeFilterPrepare`	`Searchadmin_SearchController`	EventDataContainer) `requestParams` contains the request parameters.	Fired before the request params are parsed. Note that the context request parameter will contain contextual information.
`admin.search.list.beforeListLoad`	`Searchadmin_SearchController`	EventDataContainer) `list` the search backend list, (array) `context` contain contextual information	Allows you to modify the search backend list before it is loaded.
`admin.search.list.afterListLoad`	`Searchadmin_SearchController`	EventDataContainer) `list` raw result as array, (array) `context` contain contextual information	Allows you to modify the the result after the list was loaded.

Users and Roles (\Pimcore\Model\User, \Pimcore\Model\User\Folder, \Pimcore\Model\User\Role, \Pimcore\Model\User\Role\Folder)

Name	Target	Parameters
`user.preAdd`	`Pimcore\Model\User\AbstractUser`	-
`user.postAdd`	`Pimcore\Model\User\AbstractUser`	-
`user.preUpdate`	`Pimcore\Model\User\AbstractUser`	-
`user.postUpdate`	`Pimcore\Model\User\AbstractUser`	-
`user.preDelete`	`Pimcore\Model\User\AbstractUser`	-
`user.postDelete`	`Pimcore\Model\User\AbstractUser`	-

Admin Interface

Name	Target	Parameters	Description
`admin.asset.get.preSendData`	`Admin_AssetController`
`admin.class.objectbrickList.preSendData`	`Admin_ClassController`	EventDataContainer) `returnValueContainer`, (int) `objectId`	Fired at the end of Admin_ClassController:objectbrickList() - (since build 3300)
`admin.controller.preInit`	`Zend_Controller_Action`	-
`admin.controller.postInit`	`Zend_Controller_Action`	-	Fired at the end of Pimcore_Controller_Action_Admin::init() - only fired once (2.3.1)
`admin.document.get.preSendData`	`Admin_DocumentController`
`admin.login.index.authenticate`	`Zend_Controller_Action`	(string) username,(string) `password`	Fired at the beginning of /admin/login/index if there is no valid user. Use $e-getTarget()->setUser($user); if you want to login a user in your callback
`admin.login.login.authenticate`	`Zend_Controller_Action`	(string) username,(string) `password`	Fired at the beginning of /admin/login/login before any other authentication steps are taken. Use $e-getTarget()->setUser($user); if you want to login a user in your callback
`admin.login.login.failed`	`Zend_Controller_Action`	(string) `username`,(string) `password`	Use $e-getTarget()->setUser($user); if you want to login a user in your callback
`admin.login.login.lostpassword`	`Zend_Controller_Action`	(User) `$user`, (string) `loginUrl`	Can be used to send to the user a custom and localized email containing loginUrl for password lost (default Pimcore email is automatically disabled if this event is attached)
`admin.login.logout`	`Zend_Controller_Action`	(User) `$user`
`admin.object.get.preSendData`	`Admin_ObjectController`
`admin.object.treeGetChildsById.preSendData`	`Admin_ObjectController`	EventDataContainer) `returnValueContainer`	Fired at the end of Admin_ObjectController::treeGetChildsById() - (since build 3277)

Frontend

Name	Target	Parameters	Return	Description
`frontend.error`	`Zend_Controller_Action`	(Exception) `exception`	(string) will be appended to the cache key	The return values are aggregated and are added to the cache key. This allows the customization of the error page without disabling the cache. (since 4.0)
`frontend.controller.preInit`	`Zend_Controller_Action`			(since 4.0)
`frontend.controller.postInit`	`Zend_Controller_Action`			(since 4.0)
`frontend.path.asset.image.thumbnail`	`Pimcore\Model\Asset\Image\Thumbnail`	(string) `filesystemPath` (string) `frontendPath`	(string) the modified path for the frontend	(since 4.0.1)
`frontend.path.asset.video.image-thumbnail`	`Pimcore\Model\Asset\Video\ImageThumbnail`	(string) `filesystemPath` (string) `frontendPath`	(string) the modified path for the frontend	(since 4.0.1)
`frontend.path.asset.video.thumbnail`	`Pimcore\Model\Asset\Video`	(string) `filesystemPath` (string) `frontendPath`	(string) the modified path for the frontend	(since 4.0.1)
`frontend.path.asset.document.image-thumbnail`	`Pimcore\Model\Asset\Document\ImageThumbnail`	(string) `filesystemPath`, (string) `frontendPath`	(string) the modified path for the frontend	(since 4.0.1)
`frontend.path.asset`	`Pimcore\Model\Asset`	-	(string) the modified path for the frontend	(since 4.0.1) called at the end of getFullPath()
`frontend.path.document`	`Pimcore\Model\Document`	(string) `frontendPath`	(string) the modified path for the frontend	(since 4.0.1) called at the end of getFullPath()
`frontend.path.staticroute`	`Pimcore\Model\Staticroute`	(string) `frontendPath`, (array) `params`, (bool) `reset`, (bool) `encode`	(string) the modified path for the frontend	(since 4.0.1)
`frontend.view.helper.head-link`	`Pimcore\View\Helper\HeadLink`	(stdClass) `item`		Useful to do some rewriting (since 4.3.1)
`frontend.view.helper.head-script`	`Pimcore\View\Helper\HeadScript`	(stdClass) `item`		Useful to do some rewriting (since 4.3.1)

Workflow Management

Name	Target	Parameters	Description
`workflowmanagement.preAction`	`Pimcore\WorkflowManagement\Workflow\Manager`	(string) `actionName`	Fired BEFORE any action happens in the workflow. use this to hook into actions globally and define your own logic. i.e. validation or checks on other system vars
`workflowmanagement.postAction`	`Pimcore\WorkflowManagement\Workflow\Manager`	(string) `actionName`	Fired AFTER any action happens in the workflow. Use this to hook into actions globally and define your own logic. i.e. trigger an email or maintenance job.
`workflowmanagement.preReturnAvailableActions`	allowed actions as associated array `$actionName` => `$actionConfig`	Manager `manager`	Fired when returning the available actions to a user in the admin panel. use this to further customise what actions are available to a user. i.e. stop them logging time after 5pm ;)
`workflowmanagement.action.before`	`Pimcore\WorkflowManagement\Workflow\Manager`	array `actionConfig`, array `data`
`workflowmanagement.action.success`	`Pimcore\WorkflowManagement\Workflow\Manager`	array `actionConfig`, array `data`
`workflowmanagement.action.failure`	`Pimcore\WorkflowManagement\Workflow\Manager`	array `actionConfig`, array `data`, Exception `e`

Mail

Name	Target	Parameters	Description
`mail.preSend`	`Pimcore\Mail`	EventDataContainer) `transport` contains the Zend_Mail_Transport_* if defined	Fired before an email is sent. Modify mail settings or define a custom Zend_Mail_Transport_* depending on the mail settings

Example of custom error handling using the Event API

This will prevent the user from saving News objects.

// website/var/config/startup.php
  
<?php
\Pimcore::getEventManager()->attach("object.preUpdate", function ($event) {
    $object = $event->getTarget();
    if ($object instanceof Pimcore\Model\Object\News) {
        throw new \Pimcore\Model\Element\ValidationException("YOU are NOT allowed to save such kind of objects, go away !!!", 2412);
    }
});

The error will be presented in a different way.

Plugin Error Handling

orange: the error code
green: error message
blue: link to the stack trace