Suppose we are working on a Laravel application that offers trip booking. A typical trip booking involves several steps such as:
- Booking a flight.
- Booking a hotel.
- Booking a rental car.
Our customers expect an all-or-nothing transaction — it doesn’t make sense to book a hotel without a flight. Now imagine each of these booking steps being represented by a distinct API.
Together, these steps form a distributed transaction spanning multiple services and databases. For a successful booking, all three APIs must accomplish their individual local transactions. If any step fails, the preceding successful transactions need to be reversed in an orderly fashion. With money and bookings at stake, we can’t merely erase prior transactions — we need an immutable record of attempts and failures. Thus, we should compile a list of compensatory actions for execution in the event of a failure.
Prerequisites
To follow this tutorial, you should:
- Set up a local development environment for Laravel Workflow applications in PHP or use the sample app in a GitHub codespace.
- Familiarize yourself with the basics of starting a Laravel Workflow project by reviewing the documentation.
- Review the Saga architecture pattern.
Sagas are an established design pattern for managing complex, long-running operations:
- A Saga manages transactions using a sequence of local transactions.
- A local transaction is a work unit performed by a saga participant (a microservice).
- Each operation in the Saga can be reversed by a compensatory transaction.
- The Saga pattern assures that all operations are either completed successfully or the corresponding compensation transactions are run to reverse any completed work.
Laravel Workflow provides inherent support for the Saga pattern, simplifying the process of handling rollbacks and executing compensatory transactions.
Booking Saga Flow
We will visualize the Saga pattern for our trip booking scenario with a diagram.
Workflow Implementation
We’ll begin by creating a high-level flow of our trip booking process, which we’ll name BookingSagaWorkflow.
class BookingSagaWorkflow extends Workflow
{
public function execute()
{
}
}
Next, we’ll imbue our saga with logic, by adding booking steps:
class BookingSagaWorkflow extends Workflow
{
public function execute()
{
try {
$flightId = yield ActivityStub::make(BookFlightActivity::class);
$hotelId = yield ActivityStub::make(BookHotelActivity::class);
$carId = yield ActivityStub::make(BookRentalCarActivity::class);
} catch (Throwable $th) {
}
}
}
Everything inside the try block is our "happy path". If any steps within this distributed transaction fail, we move into the catch block and execute compensations.
Adding Compensations
class BookingSagaWorkflow extends Workflow
{
public function execute()
{
try {
$flightId = yield ActivityStub::make(BookFlightActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelFlightActivity::class, $flightId));
$hotelId = yield ActivityStub::make(BookHotelActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelHotelActivity::class, $hotelId));
$carId = yield ActivityStub::make(BookRentalCarActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelRentalCarActivity::class, $carId));
} catch (Throwable $th) {
}
}
}
In the above code, we sequentially book a flight, a hotel, and a car. We use the $this->addCompensation() method to add a compensation, providing a callable to reverse a distributed transaction.
Executing the Compensation Strategy
With the above setup, we can finalize our saga and populate the catch block:
class BookingSagaWorkflow extends Workflow
{
public function execute()
{
try {
$flightId = yield ActivityStub::make(BookFlightActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelFlightActivity::class, $flightId));
$hotelId = yield ActivityStub::make(BookHotelActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelHotelActivity::class, $hotelId));
$carId = yield ActivityStub::make(BookRentalCarActivity::class);
$this->addCompensation(fn () => ActivityStub::make(CancelRentalCarActivity::class, $carId));
} catch (Throwable $th) {
yield from $this->compensate();
throw $th;
}
}
}
Within the catch block, we call the compensate() method, which triggers the compensation strategy and executes all previously registered compensation callbacks. Once done, we rethrow the exception for debugging.
By default, compensations execute sequentially. To run them in parallel, use $this->setParallelCompensation(true). To ignore exceptions that occur inside compensation activities while keeping them sequential, use $this->setContinueWithError(true) instead.
Testing the Workflow
Let’s run this workflow with simulated failures in each activity to fully understand the process.
First, we run the workflow normally to see the sequence of bookings: flight, then hotel, then rental car.
Next, we simulate an error with the flight booking activity. Since no bookings were made, the workflow logs the exception and fails.
Then, we simulate an error with the hotel booking activity. The flight is booked successfully, but when the hotel booking fails, the workflow cancels the flight.
Finally, we simulate an error with the rental car booking. The flight and hotel are booked successfully, but when the rental car booking fails, the workflow cancels the hotel first and then the flight.
Conclusion
In this tutorial, we implemented the Saga architecture pattern for distributed transactions in a microservices-based application using Laravel Workflow. Writing Sagas can be complex, but Laravel Workflow takes care of the difficult parts such as handling errors and retries, and invoking compensatory transactions, allowing us to focus on the details of our application.
