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

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