Series: Building Flipnzee Auctions – From Prototype to Production
Lesson: 120

---

Introduction

Over the previous lessons, the Flipnzee Auctions plugin has gained several important capabilities. It can create auctions, record winning bids, manage transactions, process payments, and guide administrators through ownership transfers.

Although these features work together, they currently rely on individual events rather than a centralized workflow. A payment completion triggers one action, an ownership transfer triggers another, and each component makes decisions independently.

As the plugin grows to support Escrow.com, additional payment providers, automated notifications, and buyer dashboards, this approach becomes increasingly difficult to maintain.

In this lesson, the plugin takes another significant architectural step by introducing a Transaction State Machine.

Instead of asking:

What event just happened?

the system will begin asking:

What is the current state of this transaction?

This subtle change lays the foundation for a much more scalable and maintainable architecture.

---

Why a State Machine?

Consider the complete journey of a website sale.

Auction Won

↓

Payment Pending

↓

Payment Completed

↓

Website Files Transfer

↓

Database Transfer

↓

Domain Transfer

↓

Buyer Verification

↓

Completed

Previously, these stages existed only as business knowledge in the administrator’s mind.

The plugin itself had no single place describing where a transaction currently stood.

A transaction state machine changes that.

Every transaction now progresses through a defined sequence of states that represent its lifecycle.

---

Problems Without States

Without a state machine, different parts of the plugin ask different questions.

The payment manager asks:

Has payment completed?

The transfer manager asks:

Which transfer steps are finished?

The notification system asks:

Which email should I send?

The Escrow integration will eventually ask:

Should Escrow.com be created now?

Each component ends up making its own assumptions.

Eventually those assumptions become inconsistent.

---

A Better Architecture

Instead of every component deciding independently, every component will consult the same source of truth.

Transaction

↓

Current State

↓

Business Logic

↓

Actions

Examples:

payment_pending

↓

Display payment instructions

---

payment_completed

↓

Create ownership transfer

---

database_transfer

↓

Show migration progress

---

completed

↓

Archive transaction

---

State vs Event

This distinction is extremely important.

An event describes something that happened.

Payment Completed

A state describes where the transaction is now.

Payment Verified

Events are temporary.

States persist.

Events trigger transitions between states.

---

Initial Transaction States

The first version of the state machine introduces the following lifecycle.

payment_pending

↓

payment_submitted

↓

payment_completed

↓

files_transfer

↓

database_transfer

↓

domain_transfer

↓

buyer_verification

↓

completed

Additional states such as:

• cancelled
• refunded
• disputed
• escrow_pending

can be added later without redesigning the plugin.

---

Centralizing State Definitions

Rather than scattering strings throughout dozens of PHP files, Lesson 120 introduces a dedicated class responsible for transaction states.

For example:

Flipnzee_Transaction_State_Manager::PAYMENT_PENDING

Flipnzee_Transaction_State_Manager::PAYMENT_COMPLETED

Flipnzee_Transaction_State_Manager::COMPLETED

This provides:

• one authoritative location
• fewer typing mistakes
• easier refactoring
• future localization support

---

Preparing for Escrow

One of the main goals of this refactoring project is preparing Flipnzee Auctions for external providers such as Escrow.com.

Escrow workflows are inherently state-based.

For example:

Auction Won

↓

Escrow Created

↓

Buyer Funded Escrow

↓

Seller Delivered Website

↓

Buyer Accepted

↓

Escrow Released

Rather than hardcoding Escrow logic into payment pages, the provider will simply observe state transitions.

That is only possible because the plugin now has a formal transaction state machine.

---

Benefits

By the end of this lesson, Flipnzee Auctions will gain:

• centralized transaction states
• reusable state labels
• helper methods
• lifecycle awareness
• cleaner business logic
• stronger preparation for Escrow integration

Most importantly, the plugin will move away from isolated procedural actions toward a genuine workflow engine.

---

Coming Next

In the implementation lesson, the plugin will:

• create a Transaction State Manager
• define state constants
• centralize state labels
• provide helper methods
• introduce version 1.4.0 database migration
• prepare persistent transaction states
• connect the Lifecycle Manager to the new architecture

The result will be a much more maintainable transaction workflow that future lessons can build upon.

---