Download the PHP package johmanx10/transaction without Composer

Introduction

Transaction handles operations with automatic rollback mechanisms.

A transaction consists of operations. When an operation fails, it traverses back up the chain, rolling back all previous operations in reverse order.

Assume a situation where filesystem operations need to be automated. If a part of the operations fail, the filesystem needs to be restored to the state before all operations were applied. Given the following operations:

1. Create directory my-app
2. Copy file dist/console to my-app/bin/console
3. Add executable rights to my-app/bin/console

This will be handled as follows:

1. ✔ Create directory my-app.
2. ∴ Copy file dist/console to my-app/bin/console - Directory my-app/bin does not exist.
3. ✔ Rollback: if my-app/bin/console exists, remove it.
4. ✔ Rollback: if my-app exists, remove it.

An example of the above can be tested locally by running examples/file-operations from a command line terminal.

Every operation is responsible for defining their own rollback mechanism. That way, complex nested structures to check and roll back operations can be constructed vertically.

Installation

Processing operations

To process a list of ordered operations, either use a transaction, or a handler.

Transaction

A transaction is more straight-forward and better suited to less complicated transactional scripts.

Operation Handler

The operation handler is better suited in a service oriented application. It allows to prepare visitors separate from the invoking code and thus separates concerns about operations and their visitors.

The operation exception removes a lot of boiler plate code caused by the different exception formatters.

See a working example by running:

Defining an operation

To create an operation, implement the OperationInterface, DescribableOperationInterface or use the existing Operation class to create an inline operation:

Formatting operations and exceptions

To better identify the operation, the operation failure or a specific exception, a number of formatters are available to help with debugging failed operations, chains of rolled back operations or failing rollbacks.

Operation formatter

The operation formatter can be used to format an operation. If an operation implements the DescribableOperationInterface, it can be converted to string and will be represented as such. Otherwise, it will create a generic representation, with a unique identifier for the operation.

Operation failure formatter

An operation failure consists of an operation and optionally an exception.

When an operation failure is formatted, it determines a strategy based on whether an exception is set.

If an exception is set, the result will be marked with ∴ and uses the exception message as description. When no exception is present, the result will be marked with ✔ and uses the formatted operation as description.

An operation failure is formatted using the following pattern:

In order, these show an operation failure with and without exception:

Rollback formatter

The rollback formatter can be used to format caught instances of TransactionRolledBackException.

If the code above tries to process 3 operations, but encounters a problem at the second operation, the formatted output may look something like:

This shows that the first operation (2) succeeded and the second operation (6) failed. At that point the operations were rolled back in reverse order.

See a working example by running:

Failed rollback formatter

When operations are rolled back and midway one of the operations breaks on the rollback, the FailedRollbackException will be thrown. It can be formatted using the failed rollback formatter:

When operations Foo, Bar, Baz and Qux are executed in order and the operation breaks at Qux, the rollback starts from Qux and moves back up. If the rollback for Bar then breaks, the formatted output may look something like:

This shows that the operation for Qux breaks the chain. Baz could be successfully rolled back, but Bar could not and Foo is therefore completely missing from this picture, because a rollback for Foo was never attempted.

The exception uses the following format:

And if there have been previous rollbacks, the following is appended:

Visiting operations

The default implementation of Transaction implements the interface \Johmanx10\Transaction\Visitor\AcceptingTransactionInterface, allowing it to accept operation visitors, implementing \Johmanx10\Transaction\Visitor\OperationVisitorInterface.

This can be used to gather information about operations that are executed during a transaction commit.

The following shows how to log every operation that is about to be executed within the transaction: