One of the biggest strengths of WordPress is its hook system. Actions and filters allow plugins to communicate with each other without becoming tightly coupled.

In Lesson 56, I took another important architectural step in the development of Flipnzee Auctions by introducing the plugin’s first public lifecycle hook.

Although this lesson adds no visible frontend features, it lays the foundation for future integrations with Flipnzee Analytics and other Flipnzee plugins.

---

Why This Lesson Was Needed

In Lesson 55, I implemented Automatic Auction Lifecycle Management.

Whenever active auctions are retrieved, the plugin now automatically checks for expired auctions and updates their status from Active to Closed.

The feature worked perfectly.

However, there was one limitation.

Only the Auction Manager knew that an auction had been closed.

No other plugin had any way of knowing that an important event had just occurred.

As the Flipnzee ecosystem grows, this would become a problem.

---

Thinking Beyond a Single Plugin

Although Flipnzee Auctions and Flipnzee Analytics are separate plugins, they have always been designed to complement each other.

For example, when an auction closes, future versions of Flipnzee Analytics might want to:

• Update marketplace statistics.
• Refresh dashboard widgets.
• Record lifecycle events.
• Generate reports.
• Trigger conversion tracking.

Without a proper communication mechanism, Analytics would have to modify the Auctions plugin directly.

That isn’t good software architecture.

Instead, the Auctions plugin should simply announce that something has happened and allow any interested plugin to respond.

This is exactly what WordPress Actions were designed to do.

---

Understanding WordPress Actions

A WordPress Action works like an announcement.

Instead of calling another plugin directly, the Auctions plugin simply says:

“I’ve finished processing expired auctions.”

Any plugin that is interested can choose to listen.

If no plugin is listening, nothing happens.

This keeps every plugin independent while still allowing them to work together.

---

Creating the First Flipnzee Lifecycle Event

Inside the update_expired_auctions() method, I first stored the update result in a variable.

$updated_count = ( false === $result ) ? 0 : (int) $result;

Rather than immediately returning the value, I introduced the plugin’s first public action.

do_action(
    'flipnzee_auctions_expired_processed',
    $updated_count
);

Finally, the method returns the number of auctions that were updated.

return $updated_count;

This small change transformed the method from simply updating the database into publishing an event that other plugins can respond to.

---

Why Use an Intermediate Variable?

Previously, the method ended like this:

return ( false === $result ) ? 0 : (int) $result;

That worked perfectly.

However, since the update count now needs to be passed to the action, storing it in a variable makes the code much clearer.

The same value is now:

• passed to the WordPress Action
• returned to the calling method

without repeating the calculation.

---

Improving the Documentation

Since this hook is intended for other developers, I also expanded its documentation.

Instead of simply stating that expired auctions had been processed, the comment now explains:

• why the hook exists
• when it fires
• the parameter it passes
• examples of how future plugins might use it

Good documentation is especially important for public hooks because they become part of the plugin’s public API.

---

An Architectural Decision

During implementation, we briefly considered adding a listener inside the Auctions plugin itself using:

add_action(
    'flipnzee_auctions_expired_processed',
    ...
);

The purpose would have been to demonstrate how the hook worked.

After reviewing the architecture, however, we decided against it.

Adding a listener that only writes to the error log would introduce demonstration code into the production plugin without providing any real functionality.

Instead, we chose to keep the plugin clean.

The hook now exists and is fully documented.

Future plugins can use it whenever they genuinely need to respond to the auction lifecycle.

I believe this results in a much cleaner and more professional design.

---

Preparing the Flipnzee Ecosystem

One of the goals of the Flipnzee Platform is allowing independent plugins to work together without directly depending on each other.

This hook is the first step toward that vision.

Future plugins may simply register their own listeners.

For example:

add_action(
    'flipnzee_auctions_expired_processed',
    'my_custom_function'
);

The Auctions plugin doesn’t need to know anything about that plugin.

Likewise, the Analytics plugin doesn’t need to modify the Auctions plugin.

Each plugin remains independent while communicating through WordPress itself.

---

Testing the Implementation

Since this lesson focused on architecture rather than frontend functionality, testing was straightforward.

After implementing the new hook:

• The plugin passed PHP syntax validation.
• Automatic auction expiry continued to function exactly as before.
• Existing functionality remained unaffected.
• The new lifecycle event is now available for future integrations.

Because no listeners are currently registered, introducing the hook does not change the behaviour of the plugin.

Instead, it quietly prepares the foundation for future development.

---

Lessons Learned

This lesson reminded me that professional software development isn’t always about adding visible features.

Sometimes the most valuable improvements are architectural.

By introducing a public lifecycle event, the plugin has become significantly more extensible without increasing complexity.

Future features such as analytics updates, email notifications, activity logging, and marketplace statistics can all be built on top of this single hook.

---

Looking Ahead

With the first lifecycle event now in place, the plugin is ready for even greater automation.

The next logical step is to ensure auction maintenance happens automatically in the background using WordPress scheduling, rather than only when visitors load auction pages.

That will allow the lifecycle events introduced in this lesson to fire regardless of whether anyone is currently browsing the website.

Download Source Code

Download the starting version of the plugin before the lesson:

Download the completed version after this lesson:

---

Conclusion

Lesson 56 introduced the first public WordPress Action in Flipnzee Auctions.

Although visitors won’t notice any visual changes, this small addition represents an important architectural milestone.

The plugin now follows a more event-driven design, making it easier for Flipnzee Analytics and future plugins to integrate cleanly without modifying the core Auctions plugin.

As the Flipnzee Platform continues to grow, these well-documented hooks will become the foundation that allows multiple plugins to work together while remaining independent, maintainable, and true to WordPress development best practices.

While developing the Flipnzee Auctions plugin, an interesting edge case was discovered. Auctions that were manually marked as Closed from the admin dashboard continued to display a live countdown timer on the frontend. Although bidding was no longer possible, visitors still saw that the auction had many days remaining.

In this lesson, the auction display was updated so that manually closed auctions are presented consistently throughout the website.

---

The Problem

Initially, the auction countdown relied only on the auction end date.

The logic was similar to this:

$current_time >= strtotime( $auction['auction_end'] )

This worked perfectly when an auction naturally expired, but it ignored the auction status stored in the database.

As a result:

• the auction card displayed a red Auction Ended badge,
• the bidding form was disabled,
• yet the countdown still showed something like:

Auction Ends In

41d 2h 53m

This created conflicting information for visitors.

---

Understanding the Cause

Each auction stores a status in the database.

Typical values include:

• draft
• active
• closed

When an administrator manually closes an auction, the status changes to:

closed

However, the auction end date remains unchanged because the scheduled end date is still stored for historical purposes.

Therefore, relying only on the end date was not enough.

---

Updating the Auction Logic

The auction is now considered closed if either of the following conditions is true:

• the auction status is closed, or
• the scheduled end date has already passed.

The logic now looks like this:

$auction_closed =
(
    'closed' === $auction['status']
)
||
(
    current_time( 'timestamp' ) >=
    strtotime( $auction['auction_end'] )
);

This allows the plugin to distinguish between an auction that is still active and one that has been manually closed.

---

Improving the Frontend Display

Previously, every auction displayed the countdown row.

Auction Ends In
Loading...

This has now been replaced with conditional output.

For manually closed auctions the visitor now sees:

Auction Status
Auction Ended

For active auctions the countdown remains unchanged.

Auction Ends In
12d 05h 18m

This makes the interface much clearer.

---

Preserving Winner Information

During implementation another issue was discovered.

While testing, the code responsible for retrieving the winning bid had accidentally been commented out.

Because of that:

• the Winner section disappeared,
• the plugin incorrectly displayed “No bids were placed.” even when several bids existed.

Restoring the following code resolved the problem:

$winning_bid = Flipnzee_Bid_Manager::get_winning_bid(
    $auction['id']
);

After restoring it:

• Winner information appeared correctly.
• Winning bid amount was displayed.
• Bid history continued to work.
• Closed auctions correctly showed their final results.

---

Final Behaviour

The auction system now behaves consistently.

Active Auction

• Live countdown displayed
• Bidding enabled
• Highest bidder shown
• Bid history available

Naturally Expired Auction

• Auction Ended shown
• Winner displayed
• Winning bid displayed
• No further bids accepted

Manually Closed Auction

• Auction Status → Auction Ended
• Winner displayed (if bids exist)
• Winning bid displayed
• Bid history preserved
• No misleading countdown shown

---

Lessons Learned

This implementation highlighted an important development principle.

A date alone should not always determine the state of an application. When a dedicated status field exists in the database, both the status and the timestamp should be considered before deciding how information is presented to users.

Handling these edge cases makes the auction system more reliable and provides a better experience for both buyers and sellers.

---

Download Source Code

Download the starting version of the plugin before the lesson:

Download the completed version after this lesson:

---

Conclusion

With this improvement, Flipnzee Auctions now correctly handles manually closed auctions while preserving auction history, winner information, and bid history. Visitors receive clear and accurate information regardless of whether an auction ended naturally or was closed early by an administrator, making the plugin more robust and professional.

---

As the Flipnzee Auctions plugin matured, an important database design issue became apparent. During testing, it was possible to create multiple auction records for the same listing. While acceptable during development, this behaviour could lead to incorrect auction displays, duplicated auction cards, and confusion when retrieving bid history.

In this lesson, we improved the auction creation process by enforcing a simple but important rule:

One listing can have only one auction.

Instead of creating duplicate auction records, the plugin now updates the existing auction whenever the administrator attempts to create another auction for the same listing.

---

The Problem

Originally, every time an auction was created, a new database record was inserted.

For example:

Listing ID 491

Auction #25
Auction #26
Auction #27
Auction #31

Although only one auction should exist for the listing, several records accumulated during development.

This caused problems such as:

• Multiple auction cards appearing.
• Incorrect auction selected by frontend queries.
• Bid history associated with different auction IDs.
• Difficult database maintenance.

---

Step 1: Check Whether an Auction Already Exists

Inside:

includes/class-auction-manager.php

Locate:

public static function create_auction()

Immediately after defining the database table, retrieve any existing auction for the current listing.

$existing_auction = $wpdb->get_var(
	$wpdb->prepare(
		"SELECT id
		FROM {$table}
		WHERE listing_id = %d
		LIMIT 1",
		$listing_id
	)
);

If an auction already exists, the plugin now knows its auction ID before attempting to insert another record.

---

Step 2: Update Instead of Insert

Previously, the function always continued directly to:

$wpdb->insert(

Instead, we added:

if ( $existing_auction ) {

	self::update_auction(
		$existing_auction,
		$listing_id,
		$start_price,
		$reserve_price,
		$buy_now_price,
		'active',
		$auction_start,
		$auction_end
	);

	return $existing_auction;
}

This means:

• Existing auction found → update it.
• No auction found → create a brand-new auction.

---

Step 3: Keep Existing Insert Logic

If no auction exists, the original insert code continues to run unchanged.

$result = $wpdb->insert(
	$table,
	array(
		'listing_id'    => $listing_id,
		'start_price'   => $start_price,
		'reserve_price' => $reserve_price,
		'buy_now_price' => $buy_now_price,
		'status'        => 'active',
		'auction_start' => $auction_start,
		'auction_end'   => $auction_end,
	),
	array(
		'%d',
		'%f',
		'%f',
		'%f',
		'%s',
		'%s',
		'%s',
	)
);

No further changes were required.

---

Why Return the Existing Auction ID?

The create_auction() method was originally designed to return the auction ID.

Returning:

true

would change the method’s behaviour and could break other parts of the plugin.

Instead, after successfully updating an existing auction, we return:

return $existing_auction;

This preserves the original method contract and keeps the plugin consistent.

---

Testing

To verify the implementation:

1. Edit an existing listing.
2. Create (or recreate) its auction.
3. Save the auction.
4. Check the Auctions table.

Expected behaviour:

• No new auction record is created.
• The existing auction is updated.
• The auction ID remains unchanged.
• Auction dates and prices are refreshed successfully.

Testing confirmed that the plugin now updates the existing auction instead of creating duplicates.

---

Development Observation

While testing, previously created development records remained in the database.

For example:

Listing ID 491

Auction #25 (closed)
Auction #26 (closed)
Auction #27 (closed)
Auction #31 (active)

These historical records were created before this lesson was implemented.

Because Lesson 53 prevents future duplicate creation, a clean database (or removal of old development records) ensures that each listing has only one associated auction going forward.

---

What We Learned

This lesson demonstrated an important database design principle:

Prevent duplicate data instead of fixing it later.

By checking for an existing auction before inserting a new one, the plugin now enforces a one-to-one relationship between listings and auctions. This keeps the database cleaner, simplifies frontend queries, and ensures that auction history and bid data remain associated with the correct auction record.

Download Source Code

Download the starting version of the plugin before the lesson:

Download the completed version after this lesson:

---

Final Thoughts

Although the implementation itself was straightforward, it significantly improved the overall architecture of the Flipnzee Auctions plugin. Preventing duplicate auctions not only reduces database clutter but also lays a stronger foundation for future features such as auction archives, winner announcements, relisting, and auction history. From this point onward, each listing is managed through a single auction record, making the system more reliable and easier to maintain.