Drupal 8  8.0.2
Callbacks

Functions

 callback_batch_operation ($MULTIPLE_PARAMS, &$context)
 
 callback_batch_finished ($success, $results, $operations)
 
 callback_allowed_values_function (FieldStorageDefinitionInterface $definition, FieldableEntityInterface $entity=NULL, &$cacheable=TRUE)
 

Detailed Description

Callback function signatures.

Drupal's API sometimes uses callback functions to allow you to define how some type of processing happens. A callback is a function with a defined signature, which you define in a module. Then you pass the function name as a parameter to a Drupal API function or return it as part of a hook implementation return value, and your function is called at an appropriate time. For instance, when setting up batch processing you might need to provide a callback function for each processing step and/or a callback for when processing is finished; you would do that by defining these functions and passing their names into the batch setup function.

Callback function signatures, like hook definitions, are described by creating and documenting dummy functions in a *.api.php file; normally, the dummy callback function's name should start with "callback_", and you should document the parameters and return value and provide a sample function body. Then your API documentation can refer to this callback function in its documentation. A user of your API can usually name their callback function anything they want, although a standard name would be to replace "callback_" with the module name.

See Also
Hooks
Theme system overview

Function Documentation

callback_allowed_values_function ( FieldStorageDefinitionInterface  $definition,
FieldableEntityInterface  $entity = NULL,
$cacheable = TRUE 
)

Provide the allowed values for a 'list_*' field.

Callback for options_allowed_values().

'list_*' fields can specify a callback to define the set of their allowed values using the 'allowed_values_function' storage setting.

That function will be called:

  • either in the context of a specific entity, which is then provided as the $entity parameter,
  • or for the field generally without the context of any specific entity or entity bundle (typically, Views needing a list of values for an exposed filter), in which case the $entity parameter is NULL. This lets the callback restrict the set of allowed values or adjust the labels depending on some conditions on the containing entity.

For consistency, the set of values returned when an $entity is provided should be a subset of the values returned when no $entity is provided.

Parameters
\Drupal\Core\Field\FieldStorageDefinitionInterface$definitionThe field storage definition.
\Drupal\Core\Entity\FieldableEntityInterface | null$entity(optional) The entity context if known, or NULL if the allowed values are being collected without the context of a specific entity.
bool&$cacheable(optional) If an $entity is provided, the $cacheable parameter should be modified by reference and set to FALSE if the set of allowed values returned was specifically adjusted for that entity and cannot not be reused for other entities. Defaults to TRUE.
Returns
array The array of allowed values. Keys of the array are the raw stored values (number or text), values of the array are the display labels. If $entity is NULL, you should return the list of all the possible allowed values in any context so that other code (e.g. Views filters) can support the allowed values for all possible entities and bundles.
See Also
options_allowed_values()
options_test_allowed_values_callback()
options_test_dynamic_values_callback()
callback_batch_finished (   $success,
  $results,
  $operations 
)

Complete a batch process.

Callback for batch_set().

This callback may be specified in a batch to perform clean-up operations, or to analyze the results of the batch operations.

Parameters
$successA boolean indicating whether the batch has completed successfully.
$resultsThe value set in $context['results'] by callback_batch_operation().
$operationsIf $success is FALSE, contains the operations that remained unprocessed.

References t().

Here is the call graph for this function:

callback_batch_operation (   $MULTIPLE_PARAMS,
$context 
)

Perform a single batch operation.

Callback for batch_set().

Parameters
$MULTIPLE_PARAMSAdditional parameters specific to the batch. These are specified in the array passed to batch_set().
$contextThe batch context array, passed by reference. This contains the following properties:
  • 'finished': A float number between 0 and 1 informing the processing engine of the completion level for the operation. 1 (or no value explicitly set) means the operation is finished: the operation will not be called again, and execution passes to the next operation or the callback_batch_finished() implementation. Any other value causes this operation to be called again; however it should be noted that the value set here does not persist between executions of this callback: each time it is set to 1 by default by the batch system.
  • 'sandbox': This may be used by operations to persist data between successive calls to the current operation. Any values set in $context['sandbox'] will be there the next time this function is called for the current operation. For example, an operation may wish to store a pointer in a file or an offset for a large query. The 'sandbox' array key is not initially set when this callback is first called, which makes it useful for determining whether it is the first call of the callback or not:
    if (empty($context['sandbox'])) {
    // Perform set-up steps here.
    }
    The values in the sandbox are stored and updated in the database between http requests until the batch finishes processing. This avoids problems if the user navigates away from the page before the batch finishes.
  • 'message': A text message displayed in the progress page.
  • 'results': The array of results gathered so far by the batch processing. This array is highly useful for passing data between operations. After all operations have finished, this is passed to callback_batch_finished() where results may be referenced to display information to the end-user, such as how many total items were processed.

References db_query(), db_query_range(), Drupal\entityTypeManager(), and t().

Here is the call graph for this function: