Lesson 119 Implementation – Introducing Transaction Lifecycle Events in Flipnzee Auctions
In the previous lesson, the plugin gained a complete ownership transfer workflow. Although that feature worked well, the implementation revealed an architectural issue: the payment update screen was becoming responsible for triggering multiple business processes.
This lesson introduces a cleaner, more extensible architecture by adopting WordPress action hooks as lifecycle events.
Why This Change Was Needed
Originally, when an administrator marked a payment as Completed, the payment update method was expected to:
- Update the payment status
- Create an ownership transfer record
- Record activity logs
- Trigger notifications
- Potentially communicate with Escrow.com
- Perform any future post-payment tasks
As the plugin grows, this approach would lead to a large method that becomes increasingly difficult to maintain.
Instead, the payment module should simply announce that a payment has been completed and allow other parts of the system to respond independently.
Existing Flow
Previously, the workflow looked like this:
Admin Updates Payment
│
▼
update_payment_status()
│
├── Update database
├── Create transfer
├── Send notifications
├── Escrow processing
└── More future code...
Every new feature would require modifying the payment update method.
New Event-Driven Flow
The payment screen now performs only its own responsibility.
Admin Updates Payment
│
▼
update_payment_status()
│
▼
do_action(
'flipnzee_payment_completed'
)
│
▼
Transaction Lifecycle Manager
│
├── Create ownership transfer
├── Future email notifications
├── Future Escrow integration
├── Future analytics
└── Future automation
This separates responsibilities while allowing the plugin to grow without constantly modifying the payment module.
Creating the Transaction Lifecycle Manager
A new class was introduced:
includes/
class-transaction-lifecycle-manager.php
This class becomes responsible for listening to important transaction lifecycle events.
Its initial responsibilities include:
- Registering lifecycle hooks
- Responding to completed payments
- Coordinating transfer creation
- Serving as the central point for future transaction automation
Registering the Lifecycle Event
During plugin initialization, the lifecycle manager registers a listener for completed payments.
flipnzee_payment_completed
Whenever this event is fired, the lifecycle manager automatically begins the ownership transfer workflow.
Publishing the Event
Instead of directly creating transfer records, the payment update process now publishes an event:
do_action(
'flipnzee_payment_completed',
$transaction_id
);
The payment module no longer needs to know what happens next.
Its responsibility ends after announcing that the payment has been completed.
Responding to the Event
The lifecycle manager receives the transaction ID and performs the required business logic.
Currently, it automatically:
- Creates an ownership transfer record (if one does not already exist)
Future versions will expand this handler to include:
- Buyer notifications
- Seller notifications
- Escrow.com processing
- CRM integrations
- Analytics events
- Audit logging
- Additional automation
Benefits of Event-Driven Design
This approach offers several important advantages.
Single Responsibility
The payment module focuses exclusively on payment management.
Loose Coupling
The payment module no longer depends directly on the transfer manager.
Extensibility
New features can subscribe to lifecycle events without modifying existing code.
Easier Maintenance
Each component performs one clearly defined responsibility.
Better Testing
Lifecycle handlers can be tested independently of the payment interface.
Real-World Example
After this lesson, marking a payment as Completed automatically performs the following sequence:
Administrator
│
▼
Payment Updated
│
▼
Lifecycle Event Published
│
▼
Transaction Lifecycle Manager
│
▼
Ownership Transfer Created
│
▼
Transfer appears in
Transfer Management
No additional code is required inside the payment update screen.
Result
After implementing this lesson:
- Payment completion automatically creates ownership transfer records.
- The payment module no longer contains transfer-specific logic.
- A reusable lifecycle architecture is now available.
- Future integrations can subscribe to lifecycle events without modifying existing functionality.
Looking Ahead
With lifecycle events in place, the next step is to formalize the overall transaction workflow.
Rather than treating transactions as isolated status updates, the plugin will begin managing them as a sequence of well-defined states—from auction completion through payment, ownership transfer, and final closure.
This state-based approach will provide a stronger foundation for Escrow.com integration and future automation while keeping the plugin organized as it continues to evolve.
https://github.com/SplendidDigital/flipnzee-auctions/releases/tag/lesson-119-stable