• File: CouponCodeLookupInvalidator.php
  • Full Path: /home/slvgwrnz/public_html/wp-content/plugins/woocommerce/src/Internal/Caches/CouponCodeLookupInvalidator.php
  • Date Modified: 10/26/2026 10:38 AM
  • File size: 8.41 KB
  • MIME-type: text/x-php
  • Charset: utf-8
<?php

declare( strict_types=1 );

namespace Automattic\WooCommerce\Internal\Caches;

/**
 * Invalidation handler for the coupon code to coupon id lookup cache.
 *
 * The wc_get_coupon_id_by_code() function caches the ids of the published coupons matching a
 * given code. The entries live in the 'coupons' object cache group, under the key format this
 * class owns, so WC_Cache_Helper::invalidate_cache_group( 'coupons' ) still reaches them.
 *
 * Invalidation is per coupon and happens in two layers:
 *
 * - On write, the hooks delete the lookup entry of the coupon's stored code whenever the coupon
 *   crosses the `publish` boundary or is deleted. Every other coupon's entry stays warm.
 * - On read, wc_get_coupon_id_by_code() only trusts a cached entry while every coupon id in it
 *   still belongs to a published coupon (see is_lookup_entry_stale()). The check reads the core
 *   post cache, which WordPress cleans on every post write, so it also catches what deleting one
 *   key cannot reach: the same code cached under another key (raw vs. sanitized form, surrounding
 *   whitespace, or a spelling the accent-insensitive database collation treats as equal), and a
 *   lookup that started before the delete and wrote the old id back after it.
 *
 * Known limitations:
 *
 * - The read layer describes what WC_Coupon_Data_Store_CPT resolves, so wc_get_coupon_id_by_code()
 *   only runs it while that exact data store is in use. A custom coupon data store registered
 *   through the `woocommerce_data_stores` filter may resolve further statuses, or coupons that are
 *   not posts at all, and keeps the write layer as its only coverage (what it had before this class
 *   existed). Rejecting its entries instead would disable the lookup cache for those sites, since
 *   every read would write an entry the next read throws away. The check is on the class name, so
 *   a store that extends WC_Coupon_Data_Store_CPT is treated the same way, even one that inherits
 *   get_ids_by_code() unchanged and would pass the check.
 * - Renaming the code of a coupon that stays published crosses no boundary, so the old code
 *   keeps resolving to the coupon until the cache entry expires or the coupon is unpublished.
 *   This is pre-existing behaviour, not something this class introduced. The read layer does not
 *   close it either: is_lookup_entry_stale() checks that the ids still belong to published
 *   coupons, not that they still carry the code the entry was cached under. Comparing the two in
 *   PHP would reject the aliases the database collation resolves (see the third limitation), and
 *   turn every read of such an entry into a re-resolve.
 * - wc_get_coupon_id_by_code() hashes the caller's raw input while `post_title` holds the
 *   sanitized code, so for codes with kses-escapable characters the two are different keys.
 *   Publishing a newer coupon under a code that is already cached under such a raw alias does not
 *   reach the alias, so the older coupon keeps winning that lookup until its entry is invalidated.
 * - The read-side check is only as fresh as the core post cache. A post cache entry primed by a
 *   read that raced the unpublishing write vouches for the coupon until the next post write, the
 *   same way it would for any other post type.
 *
 * @since 11.2.0
 */
class CouponCodeLookupInvalidator {

	/**
	 * The object cache group the lookup entries are stored in.
	 *
	 * @var string
	 */
	private const CACHE_GROUP = 'coupons';

	/**
	 * Register the WordPress hooks that cover coupon changes made outside the WC_Coupon CRUD.
	 *
	 * @return void
	 *
	 * @since 11.2.0
	 *
	 * @internal
	 */
	final public function init(): void {
		add_action( 'transition_post_status', array( $this, 'handle_transition_post_status' ), 10, 3 );
		add_action( 'deleted_post', array( $this, 'handle_deleted_post' ), 10, 2 );
	}

	/**
	 * Get the object cache group the lookup entries are stored in.
	 *
	 * @return string The cache group.
	 *
	 * @since 11.2.0
	 */
	public function get_cache_group(): string {
		return self::CACHE_GROUP;
	}

	/**
	 * Get the object cache key holding the ids of the published coupons with the given code.
	 *
	 * The key must be used with the cache group returned by get_cache_group().
	 *
	 * @param string $code Coupon code.
	 * @return string The cache key.
	 *
	 * @since 11.2.0
	 */
	public function get_cache_key( string $code ): string {
		// Coupon code allows spaces, which doesn't work well with some cache engines (e.g. memcached), hence the hashing.
		$hashed_code = md5( wc_strtolower( $code ) );

		return \WC_Cache_Helper::get_cache_prefix( self::CACHE_GROUP ) . 'coupon_id_from_code_' . $hashed_code;
	}

	/**
	 * Delete the cached coupon ids for the given code.
	 *
	 * @param string $code Coupon code.
	 * @return void
	 *
	 * @since 11.2.0
	 */
	public function invalidate( string $code ): void {
		if ( '' === $code ) {
			return;
		}

		wp_cache_delete( $this->get_cache_key( $code ), self::CACHE_GROUP );
	}

	/**
	 * Invalidate every code to coupon id lookup entry at once.
	 *
	 * Rotates the 'coupons' group prefix, which strands all previously cached lookup keys
	 * regardless of the code representation they were primed under, and the meta cache of every
	 * WC_Coupon along with them. Meant for bulk changes such as migrations that rewrite many
	 * codes; single coupon changes use invalidate().
	 *
	 * @return void
	 *
	 * @since 11.2.0
	 */
	public function invalidate_all(): void {
		\WC_Cache_Helper::invalidate_cache_group( self::CACHE_GROUP );
	}

	/**
	 * Check whether a cached lookup entry can no longer be trusted.
	 *
	 * An entry is stale as soon as one of its ids no longer belongs to a published coupon, i.e.
	 * the coupon was unpublished, trashed or deleted after the entry was written. The posts are
	 * read from the core post cache, which every post write cleans, so the check does not depend
	 * on which key the entry was cached under. A cold post cache costs one query for the whole
	 * entry, a warm one none.
	 *
	 * "Published coupon" is what WC_Coupon_Data_Store_CPT::get_ids_by_code() resolves, so callers
	 * must only apply this to entries that data store wrote. See the known limitations above.
	 *
	 * @param array $ids The coupon ids stored in the lookup entry.
	 * @return bool True if the entry must not be used.
	 *
	 * @since 11.2.0
	 */
	public function is_lookup_entry_stale( array $ids ): bool {
		$ids = array_filter( array_map( 'absint', $ids ) );

		if ( empty( $ids ) ) {
			return true;
		}

		// A code can be cached with more than one id. Fetch the missing posts in one query rather than one each.
		_prime_post_caches( $ids, false, false );

		foreach ( $ids as $id ) {
			$post = get_post( $id );

			if ( ! $post instanceof \WP_Post || 'shop_coupon' !== $post->post_type || 'publish' !== $post->post_status ) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Delete the lookup entry of a coupon that crosses the publish boundary.
	 *
	 * Only transitions into or out of `publish` can change which ids a code resolves to, so
	 * other status changes (e.g. draft to pending) are ignored. wp_insert_post() reports `new`
	 * as the old status, so a brand-new published coupon takes this path too, which is what lets
	 * a newer coupon published under an already cached code win the lookup.
	 *
	 * @param string   $new_status New post status.
	 * @param string   $old_status Old post status.
	 * @param \WP_Post $post       Post object.
	 * @return void
	 *
	 * @since 11.2.0
	 *
	 * @internal
	 */
	public function handle_transition_post_status( $new_status, $old_status, $post ): void {
		if ( ! $post instanceof \WP_Post || 'shop_coupon' !== $post->post_type || $new_status === $old_status ) {
			return;
		}

		if ( 'publish' === $old_status || 'publish' === $new_status ) {
			$this->invalidate( $post->post_title );
		}
	}

	/**
	 * Delete the lookup entry of a published coupon post that is deleted.
	 *
	 * The core data store only caches published coupons, so deleting a coupon in any other status
	 * cannot strand one of its entries. A custom data store can cache other statuses too, which is
	 * why WC_Coupon_Data_Store_CPT::delete() also invalidates on force delete.
	 *
	 * @param int      $post_id Post id.
	 * @param \WP_Post $post    Post object.
	 * @return void
	 *
	 * @since 11.2.0
	 *
	 * @internal
	 */
	public function handle_deleted_post( $post_id, $post ): void {
		if ( $post instanceof \WP_Post && 'shop_coupon' === $post->post_type && 'publish' === $post->post_status ) {
			$this->invalidate( $post->post_title );
		}
	}
}