<?php
/**
 * Sandhills Development Persistent Dismissible Utility
 *
 * @package SandhillsDev
 * @subpackage Utilities
 */
namespace Sandhills\Utils;

// Exit if accessed directly
defined( 'ABSPATH' ) || exit;

/**
 * This class_exists() check avoids a fatal error if this class exists in more
 * than one included plugin/theme, and should not be removed.
 */
if ( ! class_exists( 'Sandhills\Utils\Persistent_Dismissible' ) ) :

#[\AllowDynamicProperties]

/**
 * Class for encapsulating the logic required to maintain a relationship between
 * the database, a dismissible UI element with an optional lifespan, and a
 * user's desire to dismiss that UI element.
 *
 * Think of this like a WordPress Transient, but without in-memory cache support
 * and that uses the `wp_usermeta` database table instead of `wp_options`.
 *
 * @version 1.0.0
 */
class Persistent_Dismissible {

	/**
	 * Get the value of a persistent dismissible.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return mixed User meta value on success, false on failure.
	 */
	public static function get( $args = array() ) {

		// Parse arguments.
		$r = self::parse_args( $args );

		// Bail if invalid arguments.
		if ( ! self::check_args( $r ) ) {
			return false;
		}

		// Get prefixed option names.
		$eol_id       = self::get_eol_id( $r );
		$prefix       = self::get_prefix( $r );
		$prefixed_id  = $prefix . $r['id'];
		$prefixed_eol = $prefix . $eol_id;

		// Get return value & end-of-life.
		$retval   = get_user_meta( $r['user_id'], $prefixed_id,  true );
		$lifespan = get_user_meta( $r['user_id'], $prefixed_eol, true );

		// Prefer false over default return value of get_user_meta()
		if ( '' === $retval ) {
			$retval = false;
		}

		// If end-of-life, delete it. This needs to be inside get() because we
		// are not relying on WP Cron for garbage collection. This mirrors
		// behavior found inside of WordPress core.
		if ( self::is_eol( $lifespan ) ) {
			delete_user_option( $r['user_id'], $r['id'], $r['global'] );
			delete_user_option( $r['user_id'], $eol_id,  $r['global'] );
			$retval = false;
		}

		// Return the value.
		return $retval;
	}

	/**
	 * Set the value of a persistent dismissible.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return int|bool User meta ID if the option didn't exist, true on
	 *                  successful update, false on failure.
	 */
	public static function set( $args = array() ) {

		// Parse arguments.
		$r = self::parse_args( $args );

		// Bail if invalid arguments.
		if ( ! self::check_args( $r ) ) {
			return false;
		}

		// Get lifespan and prefixed option names.
		$lifespan     = self::get_lifespan( $r );
		$eol_id       = self::get_eol_id( $r );
		$prefix       = self::get_prefix( $r );
		$prefixed_id  = $prefix . $r['id'];
		$prefixed_eol = $prefix . $eol_id;

		// No dismissible data, so add it.
		if ( '' === get_user_meta( $r['user_id'], $prefixed_id, true ) ) {

			// Add lifespan.
			if ( ! empty( $lifespan ) ) {
				add_user_meta( $r['user_id'], $prefixed_eol, $lifespan, true );
			}

			// Add dismissible data.
			$retval = add_user_meta( $r['user_id'], $prefixed_id, $r['value'], true );

		// Dismissible data found in database.
		} else {

			// Plan to update.
			$update = true;

			// Dismissible to update has new lifespan.
			if ( ! empty( $lifespan ) ) {

				// If lifespan is requested but the dismissible has no end-of-life,
				// delete them both and re-create them, to avoid race conditions.
				if ( '' === get_user_meta( $r['user_id'], $prefixed_eol, true ) ) {
					delete_user_option( $r['user_id'], $r['id'], $r['global'] );
					add_user_meta( $r['user_id'], $prefixed_eol, $lifespan, true );
					$retval = add_user_meta( $r['user_id'], $prefixed_id, $r['value'], true );
					$update = false;

				// Update the lifespan.
				} else {
					update_user_option( $r['user_id'], $eol_id, $lifespan, $r['global'] );
				}
			}

			// Update the dismissible value.
			if ( ! empty( $update ) ) {
				$retval = update_user_option( $r['user_id'], $r['id'], $r['value'], $r['global'] );
			}
		}

		// Return the value.
		return $retval;
	}

	/**
	 * Delete a persistent dismissible.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return bool True on success, false on failure.
	 */
	public static function delete( $args = array() ) {

		// Parse arguments.
		$r = self::parse_args( $args );

		// Bail if invalid arguments.
		if ( ! self::check_args( $r ) ) {
			return false;
		}

		// Get the end-of-life ID.
		$eol_id = self::get_eol_id( $r );

		// Delete.
		delete_user_option( $r['user_id'], $r['id'], $r['global'] );
		delete_user_option( $r['user_id'], $eol_id,  $r['global'] );

		// Success.
		return true;
	}

	/**
	 * Parse array of key/value arguments.
	 *
	 * Used by get(), set(), and delete(), to ensure default arguments are set.
	 *
	 * @since 1.0.0
	 * @param array|string $args {
	 *     Array or string of arguments to identify the persistent dismissible.
	 *
	 *     @type string      $id       Required. ID of the persistent dismissible.
	 *     @type string      $user_id  Optional. User ID. Default to current user ID.
	 *     @type int|string  $value    Optional. Value to store. Default to true.
	 *     @type int|string  $life     Optional. Lifespan. Default to 0 (infinite)
	 *     @type bool        $global   Optional. Multisite, all sites. Default true.
	 * }
	 * @return array
	 */
	private static function parse_args( $args = array() ) {
		return wp_parse_args( $args, array(
			'id'      => '',
			'user_id' => get_current_user_id(),
			'value'   => true,
			'life'    => 0,
			'global'  => true,
		) );
	}

	/**
	 * Check that required arguments exist.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return bool True on success, false on failure.
	 */
	private static function check_args( $args = array() ) {
		return ! empty( $args['id'] ) && ! empty( $args['user_id'] );
	}

	/**
	 * Get the string used to prefix user meta for non-global dismissibles.
	 *
	 * @since 1.0.0
	 * @global WPDB $wpdb
	 * @param array $args See parse_args().
	 * @return string Maybe includes the blog prefix.
	 */
	private static function get_prefix( $args = array() ) {
		global $wpdb;

		// Default value
		$retval = '';

		// Maybe append the blog prefix for non-global dismissibles
		if ( empty( $args['global'] ) ) {
			$retval = $wpdb->get_blog_prefix();
		}

		// Return
		return $retval;
	}

	/**
	 * Get the lifespan for a persistent dismissible.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return int
	 */
	private static function get_lifespan( $args = array() ) {
		return ! empty( $args['life'] ) && is_numeric( $args['life'] )
			? time() + absint( $args['life'] )
			: 0;
	}

	/**
	 * Get the string used to identify the ID for storing the end-of-life.
	 *
	 * @since 1.0.0
	 * @param array $args See parse_args().
	 * @return string '_eol' appended to the ID (for its end-of-life timestamp).
	 */
	private static function get_eol_id( $args = array() ) {
		return sanitize_key( $args['id'] ) . '_eol';
	}

	/**
	 * Check whether a timestamp is beyond the current time.
	 *
	 * @since 1.0.0
	 * @param int $timestamp A Unix timestamp. Default 0.
	 * @return bool True if end-of-life, false if not.
	 */
	private static function is_eol( $timestamp = 0 ) {
		return is_numeric( $timestamp ) && ( $timestamp < time() );
	}
}

endif;
