Lesson 120 Implementation: Building the Transaction State Machine
Series: Building Flipnzee Auctions – From Prototype to Production
Lesson: 120 (Implementation)
Overview
In the previous lesson, we introduced the concept of a transaction state machine and explained why representing a transaction’s current state is more scalable than relying solely on events.
This implementation focuses on laying the architectural foundation for persistent transaction states.
What We Built
This lesson introduces a new class:
Flipnzee_Transaction_State_Manager
Its responsibility is to define the lifecycle of every transaction within the plugin.
Instead of scattering state strings across multiple files, all transaction states are centralized in one location.
State Constants
The following constants were added:
PAYMENT_PENDING
PAYMENT_SUBMITTED
PAYMENT_COMPLETED
FILES_TRANSFER
DATABASE_TRANSFER
DOMAIN_TRANSFER
BUYER_VERIFICATION
COMPLETED
These constants eliminate duplicated string literals and provide a single source of truth throughout the plugin.
Human-Readable Labels
A helper method was added to convert internal state identifiers into administrator-friendly labels.
Examples include:
payment_pending
↓
Payment Pending
and
database_transfer
↓
Database Transfer
This keeps presentation logic separate from business logic.
Ordered Transaction Lifecycle
The state manager now exposes the complete transaction lifecycle in a predictable order.
This makes future features—such as determining the next valid state—much easier to implement.
Rather than relying on complex conditional logic, the plugin can iterate over a centralized lifecycle definition.
Active and Terminal States
Two helper methods were introduced:
is_active()is_terminal()
These methods allow other components to determine whether a transaction is still progressing or has reached its final destination.
This abstraction will become increasingly valuable as future terminal states (such as cancelled or refunded) are introduced.
Lifecycle Integration
The Transaction Lifecycle Manager was updated to work with the new state architecture.
When payment is completed, the lifecycle manager now:
- recognizes the current transaction state
- logs the state transition
- continues creating the ownership transfer workflow
Although states are not yet fully persisted, the lifecycle manager now thinks in terms of transaction states rather than isolated events.
Database Preparation
The lesson also prepares the database for persistent transaction states through a new migration targeting version 1.4.0.
The migration introduces a dedicated state column within the transactions table.
Once applied, every transaction will permanently record its current position in the workflow.
Refactoring Existing Migrations
While extending the migration system, several improvements were made:
- corrected logging messages
- cleaned migration sequencing
- prepared a dedicated migration for transaction states
- continued following versioned database upgrades
These improvements make future schema changes easier to maintain.
Architectural Impact
Before this lesson, the transaction workflow looked like this:
Payment
↓
Transfer
↓
Completion
After Lesson 120, the architecture evolves into:
Payment
↓
Lifecycle Manager
↓
Transaction State
↓
Transfer Manager
↓
Completion
The transaction state now becomes the central reference point for every future workflow.
Why This Matters
This lesson may not introduce visible frontend changes, but it represents one of the most important architectural improvements in the project.
Upcoming features—including:
- Escrow.com integration
- multiple payment providers
- automated notifications
- buyer dashboards
- transaction timelines
- dispute handling
will all depend on a reliable transaction state machine.
By completing this refactoring now, future lessons can focus on business functionality instead of continually restructuring the underlying architecture.
Looking Ahead
With the state machine in place, the plugin is now ready to persist transaction states and allow external providers to react to state transitions.
The next lessons will leverage this foundation to integrate Escrow workflows, ensuring that every payment and ownership transfer follows a consistent, extensible lifecycle.
https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-120-stable