Creating and executing eZ Publish tasks with Mugo Queue

The Mugo Queue extension is a generic framework for queuing specific tasks in eZ Publish. It stores tasks in the ezpending_actions table and can execute such tasks in batches. It includes a ready-to-use task for re-building the eZ Find search index, whether for an entire site or only specific parts of a site. (You can build your own fetch function to re-index, say, just objects of a certain content class.) This blog post explains how to develop your own task.

You can download Mugo Queue here. Installing the extension is straightforward, as you basically need to enable the extension and regenerate the eZ Publish autoloads file. For more information, see the installation instructions in extension/mugo_queue/doc/INSTALL.

The following example explains how to create your own task within the Mugo Queue framework. This simple example removes old eZ Publish object drafts from the database. So-called "stale drafts" create editing conflicts and take up space in the database.

Cleaning up drafts is already implemented as a normal eZ Publish cronjob (see cronjobs/old_drafts_cleanup.php); however, having 2 different approaches for the same task enables you to easily see the differences between a normal cronjob and the Mugo Queue approach.

First, we create a new Mugo Task class. Create a new PHP file here:

extension/mugo_queue/classes/tasks/RemoveOldDraftsTask.php

The contents of the file is a new task class that extends the abstract MugoTask class.

class RemoveOldDraftsTask extends MugoTask
{
  public static function create( $parameters )
  {}
    
    
  public function execute( $task_id, $parameters )
  {}
}

It contains 2 required functions. The "create" function adds tasks to the queue. The "execute" function grabs a task from the queue and executes the task. Let's implement each function now:

public function create( $parameters )
{
  $return = array();
 
  // Fetches all versions matching a given status and modification limitation
  $filters = array( 'status'   => array( array( eZContentObjectVersion::STATUS_DRAFT ) ),
                    'modified' => array( '<', time() )
                    // or: 'modified' => array( '<', time() - ( 60 * 60 * 24 * 7 ) )
                  );

  $versions = eZPersistentObject::fetchObjectList( eZContentObjectVersion::definition(),
                                                   null, $filters,
                                                   null, null, false );

  if( !empty( $versions ) )
  {
      foreach( $versions as $version_row )
      {
          $return[] = $version_row[ 'id' ];
      }
  }
  else
  {
     $this->log( 'Could not find any old drafts.' );
  }

  return $return;
} 

The "create" function simply fetches all eZ Publish object versions with the status "STATUS_DRAFT". You can see a different "modified" filter as a comment. The alternative "modified" filter limits the result to object versions that are at least 7 days old. For testing purposes, you do not need to use this other filter. The function reads all version IDs from the result and returns those IDs in an array. The input variable "$parameters" comes from the command line script call and is optional. We don't need any parameters for this simple "create" function.

Here is the "execute" function:

public function execute( $task_id, $parameters )
{
  $success = false;
 
  $db = eZDB::instance();
  $db->begin();

  $version = eZContentObjectVersion::fetch( $task_id );
 
  if( $version )
  {
    $version->removeThis();
  
    //ezp API has no return value for the function removeThis() - so we need to assume success
    $success = true;
  }
 
  $db->commit();
 
  return $success;
}

The framework is responsible for getting a task out of the queue and submits the task ID to the "execute" function. The variable "$parameters" is again optional, and not needed in our example.

With the provided task ID (one of the task IDs we added in the "create" function) we fetch an eZ Publish object version. If that version still exists, we remove it. The code is wrapped in a database transaction. It is important to return a boolean value because the framework only removes the task from the queue if you return "true".

To run the code, we use a command line script. Run the script without any parameters to see all available options:

php extension/mugo_queue/bin/run.php

Now let's try our example:

1. Create a draft by editing an object and then click "Store draft and exit"
2. Add tasks into the queue:php extension/mugo_queue/bin/run.php -k RemoveOldDraftsTask -a create
3. (optional) Check if you have tasks in the queue:php extension/mugo_queue/bin/run.php -k RemoveOldDraftsTask -a list
4. Execute the tasks:php extension/mugo_queue/bin/run.php -k RemoveOldDraftsTask -a execute
5. Check if you have any remaining tasks in the queue:php extension/mugo_queue/bin/run.php -k RemoveOldDraftsTask -a list (optional)

Currently the script does not produce a lot of output, but you can check the log files var/log/mugo*.log for more information.