This module uses functionality available only in PHP 5 or later. It also requires the InnoDB engine as MyISAM tables do not support transactions. There is now a release for Drupal 6, but it has been only minimally tested.

This module supersedes and replaces the original pressflow_transaction module which is now deprecated. This implementation provides a legacy API for drop-in compatibility with code that relied on the previous module.

Transaction provides a nested transaction API modeled after Java's synchronized functions. This makes using transactions easy because there is no need to worry about transaction "garbage collection" like running COMMIT or ROLLBACK just before the function returns. This module also protects against the hazards of nested transactions and partial ROLLBACKs.

A derivative of Transaction (modified to match CiviCRM coding style) is a core component of CiviCRM 2.0.

Transaction abstraction

To start a transaction, put this at the beginning of a function that needs to operate atomically:

  $txn = new Transaction();

If something goes wrong, run this to schedule the transaction for rollback:

  $txn->rollback();

If you'd like to know whether the current transaction is scheduled to roll back (returns a boolean):

  $txn->willRollback();

Once the $txn object leaves scope, the system will perform the appropriate database operation. This means you never have to call COMMIT.

Usage notes

  • Transactions are nested, so only the database is only aware of the outermost transaction.
  • Rollbacks propagate to the outermost transaction.
  • Due to the use of LOCKs in various parts of Drupal 5 there are certain operations which will force a commit (outside of Transaction control). Examples include variable_set() and db_next_id(). This will make later attempts to COMMIT and ROLLBACK have unforeseen effects. Drupal 6 removes most (if not all) of these locks.

INSERT/UPDATE abstraction

transaction_update($table, $key_field, $fields)

$table
Table name (prefix and curly braces ("{" and "}") are not necessary)
$key_field
String (single-column primary key) or array of strings (single- or multi-column primary key). The name(s) of the column(s) to use when identifying the row to update. If only a single column is being used to select the row, this may be a string. If more than one column is being used, this must be an array of strings.
$fields
Associative array mapping column names (including key field columns if attempting to UPDATE) to values
Return value
FALSE on failure or the primary key value in scalar form (if $primary_key is a string) or an associative array mapping primary key column names to primary key column values (if $primary_key is an array)

Usage notes

  • If key field values are passed in $fields, the function will attempt to UPDATE. If the UPDATE does not match any rows, it will INSERT.
  • If no key field values are passed and the key field is one column, the function assumes it to be a primary key and will generate a primary key using a functional equivalent to db_next_id() and then INSERT.
  • If no key field values are passed and the primary key is multiple columns, the function will fail and return FALSE.

Credits

Only local images are allowed.

Development of this module is sponsored by Four Kitchens.

Project Information

  • Maintenance status: Unknown
  • Development status: Unknown
  • Module categories: Developer, Utility
  • Reported installs: 28 sites currently report using this module. View usage statistics.
  • Downloads: 1,656
  • Last modified: April 15, 2009

Downloads