Athenian Custom Stock Statuses

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Admin Workflow

The active plugin bootstrap registers a WooCommerce submenu titled Custom Stock Statuses.

From that screen, authorized WooCommerce managers can define status rows with the following fields:

| Field | Purpose | | --- | --- | | Status Key | Machine-readable key saved into WooCommerce _stock_status meta. | | Label | Human-readable status label shown in admin and storefront messaging. | | Details | Short explanatory text describing what the status means. | | Lead Time | Customer-facing fulfillment timing such as 5-10 Business Days. | | Ship Min Days | Optional numeric lower bound for shipping/fulfillment window. | | Ship Max Days | Optional numeric upper bound for shipping/fulfillment window. | | Color | Badge background color. | | Disable Add to Cart | Marks the status as non-purchasable and blocks cart additions. |

Built-in statuses are displayed in the manager and cannot be removed. Custom statuses can be added and removed from the admin table.

Storefront Workflow

When a product or variation has a custom status:

1. WooCommerce availability data is filtered.
2. The plugin resolves the product's _stock_status value.
3. The status definition is converted into a badge, details text, and lead-time line.
4. Variation payloads are enriched so selected variations can expose the correct status data.
5. Frontend JavaScript can render the selected variation details and adjust add-to-cart button state.
6. Server-side validation still blocks add-to-cart attempts when a status is configured as disabled.

This dual client/server approach allows the storefront to visually discourage purchase while still protecting checkout behavior if a user bypasses the UI.

Technical Architecture

Primary Bootstrap

The active WordPress plugin header is in:

admin-custom-stock-status.php

Detected plugin header:

Plugin Name: Admin Custom Stock Statuses
Description: Adds admin-managed custom stock statuses directly to WooCommerce native stock status options.
Version: 2.1.0

The reviewed PHP files pass php -l syntax checks.

Active Procedural Implementation

The active bootstrap file implements the main runtime behavior using apf_* helper functions. It defines default status metadata, stores custom statuses in an option, registers WooCommerce filters/actions, renders the admin page, and handles import/export and product-list filtering.

Key active helper functions include:

| Function | Purpose | | --- | --- | | apf_get_native_stock_status_definitions() | Defines enriched metadata for WooCommerce built-in statuses. | | get_custom_stock_status_details() | Merges built-in status definitions with saved custom status rows. | | apf_get_custom_only_stock_statuses() | Returns only merchant-created statuses. | | get_custom_stock_status_mapping() | Builds key/label lookup mapping for normalization. | | apf_get_stock_status_label() | Resolves a label for a status key. | | apf_get_stock_status_ship_window() | Returns min/max ship-day metadata for a status. | | apf_get_product_display_stock_status_definition() | Resolves the storefront-ready status definition for a product. | | apf_status_disables_add_to_cart() | Determines whether a status blocks purchase. | | apf_product_disables_add_to_cart() | Applies add-to-cart blocking logic to a product object. | | apf_current_product_js_state() | Builds localized frontend state for product/variation button behavior. | | apf_normalize_stock_status_value() | Converts incoming labels or keys into a known stock status key. |

Packaged Class-Based Implementation

The ZIP also contains a namespaced ACSS class-based implementation under includes/:

includes/class-acss-plugin.php
includes/class-acss-admin.php
includes/class-acss-front.php
includes/class-acss-import-export.php
includes/class-acss-statuses.php
includes/class-acss-utils.php

Those classes define a cleaner modular structure with constants such as ACSS_DIR, ACSS_URL, and ACSS_VERSION, but this ZIP's main bootstrap file does not appear to define those constants or instantiate ACSS\Plugin::instance().

For that reason, the class-based files should be treated as a bundled refactor/future implementation unless the live environment wires them in through a different loader not present in this ZIP.

Data Model

Primary WordPress Option

The active implementation stores custom status configuration in:

custom_stock_statuses

This value is referenced through:

APF_CUSTOM_STOCK_STATUSES_OPTION

The stored array is keyed by stock status key and contains status metadata such as:

[
    'built_to_order' => [
        'label' => 'Built to Order',
        'details' => 'Made after purchase.',
        'lead_time' => '5-10 Business Days',
        'ship_days_min' => 5,
        'ship_days_max' => 10,
        'color' => '#3366cc',
        'disable_add_to_cart' => 0,
    ],
]

WooCommerce Product Meta

WooCommerce stock state is saved using the native product/variation stock status meta key:

_stock_status

The plugin intentionally keeps status assignment aligned with WooCommerce's existing product and variation inventory model.

Class-Based Option Names

The bundled class implementation references these option names:

acss_statuses
acss_settings

Because the active bootstrap uses custom_stock_statuses, care should be taken before mixing or migrating between the procedural and class-based implementations.

WooCommerce Integration Points

| Hook | Purpose | | --- | --- | | wc_get_product_stock_status_options | Adds custom statuses to WooCommerce product stock-status options. | | woocommerce_product_stock_status_options | Adds custom statuses to additional WooCommerce status option contexts. | | woocommerce_process_product_meta | Saves custom stock status values for simple products. | | woocommerce_save_product_variation | Saves custom stock status values for variations. | | woocommerce_get_availability | Replaces/augments product availability text with badge/details/lead-time output. | | woocommerce_available_variation | Adds custom stock details to variation JSON payloads. | | woocommerce_add_to_cart_validation | Blocks cart additions when the selected stock status disables add-to-cart. | | woocommerce_csv_product_import_preformatted_data | Normalizes imported stock status values before product import. | | woocommerce_product_import_inserted_product_object | Persists normalized stock status after import. | | woocommerce_product_export_product_column_stock_status | Exports the product's stored stock status. | | restrict_manage_posts | Adds product-list stock-status filter dropdown. | | pre_get_posts | Filters product admin list by selected _stock_status. |

Add-to-Cart Restriction Model

Statuses can be configured to disable add-to-cart.

The plugin enforces this in two layers:

1. Frontend UI state - JavaScript disables and visually mutes native/APF add-to-cart buttons.
2. Server-side validation - woocommerce_add_to_cart_validation returns false and adds a WooCommerce error notice when a restricted product is submitted to the cart.

This avoids relying on JavaScript alone for purchase blocking.

Product Admin Filtering

The plugin adds a stock-status filter dropdown to the Products admin list screen and modifies the product query through _stock_status meta filtering.

This allows administrators to quickly find items assigned to statuses such as:

• Built to Order
• Ships from Vendor
• Out of Stock
• On Backorder
• Any site-specific status key

Security and Sanitization

The plugin uses common WordPress safeguards across the active implementation:

• defined('ABSPATH') || exit direct-access protection
• current_user_can() / WooCommerce capability checks in class admin implementation
• check_admin_referer() for status-save requests
• sanitize_key() for status keys
• sanitize_text_field() for labels, details, and lead times
• sanitize_hex_color() / hex validation for badge colors
• Numeric validation for ship-day windows
• Escaping functions such as esc_html(), esc_attr(), and wp_kses_post() in the packaged class implementation

Implementation Notes and Review Flags

1. Active bootstrap and bundled class files differ

The main active plugin file is a procedural implementation. The ZIP also contains a modular ACSS class implementation that appears more structured but is not wired by the visible bootstrap file.

Before a production refactor, decide whether to:

• Keep the procedural implementation as canonical;
• Replace it with the namespaced ACSS\Plugin loader; or
• Build a migration routine between custom_stock_statuses and acss_statuses.

2. Option-name migration should be handled carefully

The procedural and class-based implementations use different option names. If the class loader is activated, existing status definitions may not appear unless a migration step is added.

3. Variation detail container should be standardized

The frontend script renders variation details into #acss-variation-stock, but the active procedural bootstrap primarily modifies WooCommerce availability text and localizes frontend state. A theme or future plugin update should ensure the variation detail wrapper exists wherever variation-specific status messaging is expected.

4. Export format should be standardized

The active implementation exports status keys, while the class-based implementation exports labels. Both approaches can be valid, but product teams should choose one based on whether downstream systems expect human-readable labels or machine-safe keys.