<?php
/**
 * A row action, declared by a feature and rendered by an AdminSurface.
 *
 * @package Adminkeep
 */

namespace Adminkeep\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * What a feature wants offered on a post row, expressed without reference to how it is drawn.
 *
 * Features never build the markup and never name a hook. They describe the action; the surface
 * decides where it lands. That is what makes the DataViews migration a new adapter rather than a
 * rewrite of every feature.
 */
class RowAction {

	/**
	 * Stable identifier, unique within the plugin.
	 *
	 * @var string
	 */
	private $id;

	/**
	 * Callable returning the visible label. A callable, not a string, because labels are
	 * translated and this object is built at boot time — before init.
	 *
	 * @var callable
	 */
	private $label_callback;

	/**
	 * Post types this action appears on. Empty means every post type.
	 *
	 * @var string[]
	 */
	private $post_types;

	/**
	 * Capability required, checked against the individual post.
	 *
	 * @var string
	 */
	private $capability;

	/**
	 * Callable given a WP_Post, returning the action URL.
	 *
	 * @var callable
	 */
	private $url_callback;

	/**
	 * Optional callable given a WP_Post, returning whether the action applies to it.
	 *
	 * @var callable|null
	 */
	private $is_available_callback;

	/**
	 * Build from a named-argument array.
	 *
	 * An array rather than a constructor signature because PHP 7.4 has no named arguments and
	 * six positional parameters is unreadable at every call site.
	 *
	 * @param array $args {
	 *     @type string        $id                    Required. Unique id.
	 *     @type callable      $label                 Required. Returns the translated label.
	 *     @type callable      $url                   Required. Given WP_Post, returns the URL.
	 *     @type string[]      $post_types            Optional. Defaults to all.
	 *     @type string        $capability            Optional. Defaults to 'edit_post'.
	 *     @type callable|null $is_available          Optional. Given WP_Post, returns bool.
	 * }
	 */
	public function __construct( array $args ) {
		$this->id                    = isset( $args['id'] ) ? (string) $args['id'] : '';
		$this->label_callback        = isset( $args['label'] ) ? $args['label'] : '__return_empty_string';
		$this->url_callback          = isset( $args['url'] ) ? $args['url'] : '__return_empty_string';
		$this->post_types            = isset( $args['post_types'] ) ? (array) $args['post_types'] : array();
		$this->capability            = isset( $args['capability'] ) ? (string) $args['capability'] : 'edit_post';
		$this->is_available_callback = isset( $args['is_available'] ) ? $args['is_available'] : null;
	}

	/**
	 * Identifier.
	 *
	 * @return string
	 */
	public function id() {
		return $this->id;
	}

	/**
	 * Visible label, resolved now.
	 *
	 * @return string
	 */
	public function label() {
		return (string) call_user_func( $this->label_callback );
	}

	/**
	 * Declared post types. Empty means all.
	 *
	 * @return string[]
	 */
	public function post_types() {
		return $this->post_types;
	}

	/**
	 * Required capability.
	 *
	 * @return string
	 */
	public function capability() {
		return $this->capability;
	}

	/**
	 * Whether this action was declared for a post type.
	 *
	 * @param string $post_type Post type slug.
	 * @return bool
	 */
	public function applies_to( $post_type ) {
		if ( empty( $this->post_types ) ) {
			return true;
		}

		return in_array( $post_type, $this->post_types, true );
	}

	/**
	 * Whether the current user may see this action on this post.
	 *
	 * The capability is checked against the post id, so meta capabilities like edit_post map to
	 * the right primitive for this particular row. Primitive capabilities ignore the extra
	 * argument, so passing it is always safe.
	 *
	 * @param \WP_Post $post Post being rendered.
	 * @return bool
	 */
	public function is_available_for( $post ) {
		if ( ! $this->applies_to( $post->post_type ) ) {
			return false;
		}

		if ( ! current_user_can( $this->capability, $post->ID ) ) {
			return false;
		}

		if ( null !== $this->is_available_callback && ! call_user_func( $this->is_available_callback, $post ) ) {
			return false;
		}

		return true;
	}

	/**
	 * The action URL for a post.
	 *
	 * @param \WP_Post $post Post being rendered.
	 * @return string
	 */
	public function url_for( $post ) {
		return (string) call_user_func( $this->url_callback, $post );
	}
}