Pink-Crab / Perique-Registerables

src/Meta_Box.php

<?php

declare(strict_types=1);

/**
 * Meta Box model
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * @author Glynn Quelch <glynn.quelch@gmail.com>
 * @license http://www.opensource.org/licenses/mit-license.html  MIT License
 * @package PinkCrab\Registerables
 */

namespace PinkCrab\Registerables;

class Meta_Box {

	/**
	 * The meta box key
	 *
	 * @var string
	 * @required
	 */
	public string $key = '';

	/**
	 * The meta box label/title
	 *
	 * @var string
	 * @required
	 */
	public string $label = '';

	/**
	 * The view callback
	 *
	 * @var callable|null
	 */
	public $view;

	/**
	 * The view args passed to view.
	 *
	 * @var array<string, mixed>
	 */
	public array $view_vars = array();

	/**
	 * The path relative to the defined base path
	 * in config
	 *
	 * @var string|null
	 */
	public ?string $view_template = null;

	/**
	 * Screens to display meta box.
	 *
	 * @var array<int, string>
	 * @required
	 */
	public array $screen = array();

	/**
	 * Meta box context/position
	 *
	 * @var 'advanced'|'normal'|'side'

The doc comment 'advanced'|'normal'|'side' at position 0 could not be parsed: Unknown type name ''advanced'' at position 0 in 'advanced'|'normal'|'side'.

	 * @required
	 */
	public string $context = 'normal';

	/**
	 * What is the loading priority
	 *
	 * @var 'core'|'default'|'high'|'low'

The doc comment 'core'|'default'|'high'|'low' at position 0 could not be parsed: Unknown type name ''core'' at position 0 in 'core'|'default'|'high'|'low'.

	 */
	public string $priority = 'default';

	/**
	 * Define any hooks that should fire with the meta box.
	 *
	 * @var array<string, array{callback:callable,priority:int,params:int}>
	 */
	public array $actions = array();

	/**
	 * Filter for pushing post specific data into the views
	 * global variable scope
	 *
	 * @var null|callable(\WP_Post $post,array<string, mixed> $args):array<string, mixed>
	 */
	public $view_data_filter;

	/**
	 * Creates a Meta Box with a defined key.
	 *
	 * @param string $key
	 */
	final public function __construct( string $key ) {
		$this->key = $key;
	}

	/**
	 * Creates a full width meta box with a defined key.
	 *
	 * @param string $key
	 * @return self
	 */
	public static function normal( string $key ): self {
		$meta_box          = new static( $key );
		$meta_box->context = 'normal';
		return $meta_box;
	}

	/**
	 * Creates a full width meta box with a defined key.
	 *
	 * @param string $key
	 * @return self
	 */
	public static function side( string $key ): self {
		$meta_box          = new static( $key );
		$meta_box->context = 'side';
		return $meta_box;
	}

	/**
	 * Sets the label
	 *
	 * @param string $label
	 * @return self
	 */
	public function label( string $label ): self {
		$this->label = $label;
		return $this;
	}

	/**
	 * Sets the screens this meta box will be loaded.
	 *
	 * @param string|array<mixed>|\WP_Screen $screen
	 * @return self
	 */
	public function screen( $screen ): self {
		array_push( $this->screen, $screen );
		return $this;
	}

	/**
	 * Sets the view args.
	 *
	 * @param array<string, mixed> $view_vars
	 * @return self
	 */
	public function view_vars( array $view_vars ): self {
		$this->view_vars = $view_vars;
		return $this;
	}

	/**
	 * Sets the views template path.
	 * Should be relative to the base path defined in config.
	 *
	 * @param string $view_template
	 * @return self
	 */
	public function view_template( string $view_template ): self {
		$this->view_template = $view_template;
		return $this;
	}

	/**
	 * Sets the view method.
	 * Can be a callable or a function or class|method array.
	 *
	 * @param callable $view_callback
	 * @return self
	 */
	public function view( $view_callback ): self {
		$this->view = $view_callback;
		return $this;
	}

	/**
	 * Adds a acton to be defined as a hook key and callable|function
	 *
	 * @param string   $hook
	 * @param callable $callback
	 * @param int $priority
	 * @param int $params
	 * @return self
	 */
	public function add_action( string $hook, callable $callback, int $priority = 10, int $params = 1 ): self {
		$this->actions[ $hook ] =
			array(
				'callback' => $callback,
				'priority' => $priority,
				'params'   => $params,
			);
		return $this;
	}


	/**
	 * Set $args):args
	 *
	 * @param callable(\WP_Post $post,array<string, mixed> $args):array<string, mixed> $view_data_filter
	 * @return self
	 */
	public function view_data_filter( callable $view_data_filter ): self {
		$this->view_data_filter = $view_data_filter;
		return $this;
	}
}