Documentation

CRM_Core_Transaction
in package

Tags
copyright

CiviCRM LLC https://civicrm.org/licensing

copyright

David Strauss david@fourkitchens.com (c) 2007

(Note: This has been considerably rewritten; the interface is preserved for backward compatibility.)

Transaction management in Civi is divided among three classes:

  • CRM_Core_Transaction: API. This binds to __construct() + __destruct() and notifies the transaction manager when it's OK to begin/end a transaction.
  • Civi\Core\Transaction\Manager: Tracks pending transaction-frames
  • Civi\Core\Transaction\Frame: A nestable transaction (e.g. based on BEGIN/COMMIT/ROLLBACK or SAVEPOINT/ROLLBACK TO SAVEPOINT).

Examples:

// Some business logic using the helper functions
function my_business_logic() {
  CRM_Core_Transaction::create()->run(function($tx) {
    ...do work...
   if ($error) throw new Exception();
  });
}

// Some business logic which returns an error-value
// and explicitly manages the transaction.
function my_business_logic() {
  $tx = new CRM_Core_Transaction();
  ...do work...
  if ($error) {
    $tx->rollback();
    return error_value;
  }
}

// Some business logic which uses exceptions
// and explicitly manages the transaction.
function my_business_logic() {
  $tx = new CRM_Core_Transaction();
  try {
    ...do work...
  } catch (Exception $ex) {
    $tx->rollback()->commit();
    throw $ex;
  }
}

Note: As of 4.6, the transaction manager supports both reference-counting and nested transactions (SAVEPOINTs). In the past, it only supported reference-counting. The two cases may exhibit different systemic effects with respect to unhandled exceptions.

Table of Contents

Constants

PHASE_POST_COMMIT  = 2
PHASE_POST_ROLLBACK  = 8
PHASE_PRE_COMMIT  = 1
These constants represent phases at which callbacks can be invoked.
PHASE_PRE_ROLLBACK  = 4

Properties

$_pseudoCommitted  : bool
Whether commit() has been called on this instance of CRM_Core_Transaction

Methods

__construct()  : mixed
Ensure that an SQL transaction is started.
__destruct()  : mixed
addCallback()  : mixed
Add a transaction callback.
addPostCommit()  : mixed
Whenever hook_civicrm_post fires, schedule an equivalent call to hook_civicrm_postCommit.
commit()  : CRM_Core_Exception
Immediately commit or rollback.
create()  : CRM_Core_Transaction
Ensure that an SQL transaction is started.
forceRollbackIfEnabled()  : mixed
Force an immediate rollback, regardless of how many any CRM_Core_Transaction objects are waiting for pseudo-commits.
isActive()  : mixed
Determine whether there is a pending transaction.
rollback()  : CRM_Core_Transaction
Mark the transaction for rollback.
rollbackIfFalse()  : mixed
run()  : CRM_Core_Transaction
Execute a function ($callable) within the scope of a transaction. If $callable encounters an unhandled exception, then rollback the transaction.
willCommit()  : bool

Constants

PHASE_POST_COMMIT

public mixed PHASE_POST_COMMIT = 2

PHASE_POST_ROLLBACK

public mixed PHASE_POST_ROLLBACK = 8

PHASE_PRE_COMMIT

These constants represent phases at which callbacks can be invoked.

public mixed PHASE_PRE_COMMIT = 1

PHASE_PRE_ROLLBACK

public mixed PHASE_PRE_ROLLBACK = 4

Properties

$_pseudoCommitted

Whether commit() has been called on this instance of CRM_Core_Transaction

private bool $_pseudoCommitted = \FALSE

Methods

__construct()

Ensure that an SQL transaction is started.

public __construct([bool $nest = FALSE ]) : mixed
Parameters
$nest : bool = FALSE

Determines what to do if there's currently an active transaction:.

  • If true, then make a new nested transaction ("SAVEPOINT")
  • If false, then attach to the existing transaction

addCallback()

Add a transaction callback.

public static addCallback(int $phase, callable $callback[, mixed $params = NULL ][, string|int|null $id = NULL ]) : mixed

Note: It's conceivable to add callbacks to the main/overall transaction (aka $manager->getBaseFrame()) or to the innermost nested transaction (aka $manager->getFrame()). addCallback() has been used in the past to work-around deadlocks. This may or may not be necessary now -- but it seems more consistent (for b/c purposes) to attach callbacks to the main/overall transaction.

Pre-condition: isActive()

Parameters
$phase : int

A constant; one of: self::PHASE_{PRE,POST}_{COMMIT,ROLLBACK}.

$callback : callable

A PHP callback.

$params : mixed = NULL

Optional values to pass to callback. See php manual call_user_func_array for details.

$id : string|int|null = NULL

addPostCommit()

Whenever hook_civicrm_post fires, schedule an equivalent call to hook_civicrm_postCommit.

public static addPostCommit(PostEvent $e) : mixed
Parameters
$e : PostEvent
Tags
see
CRM_Utils_Hook::post

create()

Ensure that an SQL transaction is started.

public static create([bool $nest = FALSE ]) : CRM_Core_Transaction

This is a thin wrapper around __construct() which allows more fluent coding.

Parameters
$nest : bool = FALSE

Determines what to do if there's currently an active transaction:.

  • If true, then make a new nested transaction ("SAVEPOINT")
  • If false, then attach to the existing transaction
Return values
CRM_Core_Transaction

forceRollbackIfEnabled()

Force an immediate rollback, regardless of how many any CRM_Core_Transaction objects are waiting for pseudo-commits.

public static forceRollbackIfEnabled() : mixed

Only rollback if the transaction API has been called.

This is only appropriate when it is certain that the callstack will not wind-down normally -- e.g. before a call to exit().

isActive()

Determine whether there is a pending transaction.

public static isActive() : mixed

rollbackIfFalse()

public static rollbackIfFalse(mixed $flag) : mixed
Parameters
$flag : mixed

run()

Execute a function ($callable) within the scope of a transaction. If $callable encounters an unhandled exception, then rollback the transaction.

public run(callable $callable) : CRM_Core_Transaction

After calling run(), the CRM_Core_Transaction object is "used up"; do not use it again.

Parameters
$callable : callable

Should expect one parameter (CRM_Core_Transaction).

Tags
throws
Exception
Return values
CRM_Core_Transaction

willCommit()

public static willCommit() : bool
Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results