Understanding and developing fetch functions

How it works

A fetch function is actually part of a module and is mainly composed of 2 files :

• Definition file (function_definition.php)
• Function collection class (class where your PHP functions will reside as static methods), that will be named <MyModule>FunctionCollection (replace <MyModule> by the name of your module)

You can get many examples in modules from eZ Publish kernel, take a look into kernel/content/ folder for example (please note that every folders located under kernel/, except classes/ and common/, contain a module).

The definition file

Basically, this file (function_definition.php) holds an associative array called $FunctionList. Keys of this array are fetch functions names and values are the definition as another associative array :

<?php
// function_definition.php
// Fetch definition file
$FunctionList = array();

$FunctionList['fetch_function_name'] = array(
    'name' => 'fetch_function_name', // Retype the name of your function
    'operation_types' => 'read', // Obsolete, for BC
    'call_method' => array(
        'class' => 'MyModuleFunctionCollection', // Function collection class
        'method' => 'getMyFetchFunctionResult' ), // Method to call
    'parameter_type' => 'standard', // Obsolete, for BC
    'parameters' => array( // Function parameters in the PHP function order
        array( 'name' => 'first_param',
               'type' => 'string',
               'required' => true ),
        array( 'name' => 'second_param',
               'type' => 'boolean',
               'required' => false,
               'default' => false )
    )
);

Above is a typical fetch definition file. You will find similar ones in the kernel or in extensions from the community (take a look into the SQLIGeoloc one).

The function collection

As I said before, your PHP fetch function will be contained in a so called function collection, which is a simple PHP class with static methods. Fetch code needs to be written in one of those static methods.

The main point to remember about these methods is the argument order. It must be strictly the same than declared in the definition file. Thus, in the example above, first_param will be mapped to the method's first argument, and second_param to the second.

Each method must return an associative array, with result as key and the value to be returned as value. If an error occurs, then it must return an associative array, with error as key and the error message as value.

<?php
/**
 * MyModule fetch functions
 */
class MyModuleFunctionCollection
{
    /**
     * Fetch function code.
     * You can do everything you want here.
     * Just return an associative array with 'result' as key and your result as value.
     * If an error is raised, return an associative array with 'error' as key and the
     * error message as value
     * @param string $myFirstParam first_param declared in function_definition.php
     * @param string $mySecondParam second_param declared in function_definition.php
     */
    public static function getMyFetchFunctionResult( $myFirstParam, $mySecondParam = false )
    {
        try
        {
            /*
             * Do everything you want here to fetch/aggregate your data
             * Associative arrays can be used in templates :
             * {def $result = fetch( 'mymodule', 'fetch_function_name', hash(
             *       'first_param', 'something',
             *       'second_param', true()
             * ) )}
             * {$result.first_key} {* Will display "foo" *}
             * {$result.second_key} {* Will display "bar" *}
             */
              $result = array(
                'first_key'      => 'foo',
                'second_key'     => 'bar'
            );
            
            return array( 'result' => $result );
        }
        catch( Exception $e )
        {
            $errMsg = $e->getMessage();
            eZDebug::writeError( $errMsg );
            return array( 'error' => $errMsg );
        }
    }
}