JezK

Edit File: posts-query.php

<?php

// phpcs:disable Yoast.NamingConventions.NamespaceName.TooLong -- Needed in the folder structure.
namespace Yoast\WP\SEO\Bulk_Editor\Domain\Posts;

/**
 * Describes a request for a page of bulk editor posts.
 *
 * Carries every parameter the collectors need so new filters (status, quality) can be added
 * to this object instead of growing the collector method signatures.
 */
class Posts_Query {

/**
	 * The content type to get posts for.
	 *
	 * @var string
	 */
	private $content_type;

/**
	 * The page of results to get, starting at 1.
	 *
	 * @var int
	 */
	private $page;

/**
	 * The number of posts per page.
	 *
	 * @var int
	 */
	private $per_page;

/**
	 * The search term to filter posts by, or an empty string for no search.
	 *
	 * @var string
	 */
	private $search;

/**
	 * The post statuses to include.
	 *
	 * @var array<string>
	 */
	private $statuses;

/**
	 * The author to limit posts to, or null for no author restriction.
	 *
	 * @var int|null
	 */
	private $author_id;

/**
	 * The needs-improvement fields to filter by — a field matches when empty, or (for search fields with SEO
	 * analysis enabled) when its per-field score needs improvement — or an empty array for no such filter.
	 *
	 * @var array<string>
	 */
	private $needs_improvement;

/**
	 * Whether the per-field scores may back the needs-improvement filter. False when SEO analysis is
	 * disabled, so the filter falls back to the empty-field check only.
	 *
	 * @var bool
	 */
	private $scores_enabled;

/**
	 * The post IDs to limit posts to, or an empty array for no restriction.
	 *
	 * @var array<int>
	 */
	private $include_ids;

/**
	 * The constructor.
	 *
	 * @param string        $content_type      The content type to get posts for.
	 * @param int           $page              The page of results to get, starting at 1.
	 * @param int           $per_page          The number of posts per page.
	 * @param string        $search            The search term, or an empty string for no search.
	 * @param array<string> $statuses          The post statuses to include.
	 * @param int|null      $author_id         The author to limit posts to, or null for no author restriction.
	 * @param array<string> $needs_improvement The needs-improvement fields to filter by (a field matches when empty, or — for search fields with SEO analysis enabled — when its per-field score needs improvement), or an empty array for no such filter.
	 * @param bool          $scores_enabled    Whether the per-field scores may back the needs-improvement filter.
	 * @param array<int>    $include_ids       The post IDs to limit posts to, or an empty array for no restriction.
	 */
	public function __construct(
		string $content_type,
		int $page,
		int $per_page,
		string $search,
		array $statuses,
		?int $author_id = null,
		array $needs_improvement = [],
		bool $scores_enabled = true,
		array $include_ids = []
	) {
		$this->content_type      = $content_type;
		$this->page              = $page;
		$this->per_page          = $per_page;
		$this->search            = $search;
		$this->statuses          = $statuses;
		$this->author_id         = $author_id;
		$this->needs_improvement = $needs_improvement;
		$this->scores_enabled    = $scores_enabled;
		$this->include_ids       = $include_ids;
	}

/**
	 * Returns the content type to get posts for.
	 *
	 * @return string The content type.
	 */
	public function get_content_type(): string {
		return $this->content_type;
	}

/**
	 * Returns the page of results to get.
	 *
	 * @return int The page, starting at 1.
	 */
	public function get_page(): int {
		return $this->page;
	}

/**
	 * Returns the number of posts per page.
	 *
	 * @return int The number of posts per page.
	 */
	public function get_per_page(): int {
		return $this->per_page;
	}

/**
	 * Returns the search term.
	 *
	 * @return string The search term, or an empty string for no search.
	 */
	public function get_search(): string {
		return $this->search;
	}

/**
	 * Returns whether a search term is set.
	 *
	 * @return bool Whether a search term is set.
	 */
	public function has_search(): bool {
		return $this->search !== '';
	}

/**
	 * Returns the post statuses to include.
	 *
	 * @return array<string> The post statuses.
	 */
	public function get_statuses(): array {
		return $this->statuses;
	}

/**
	 * Returns the fields that must be empty for a post to be included.
	 *
	 * @return array<string> The fields, or an empty array for no such filter.
	 */
	public function get_needs_improvement(): array {
		return $this->needs_improvement;
	}

/**
	 * Returns whether the per-field scores may back the needs-improvement filter.
	 *
	 * @return bool Whether the scores may be used; false falls back to the empty-field check only.
	 */
	public function are_scores_enabled(): bool {
		return $this->scores_enabled;
	}

/**
	 * Returns the author to limit posts to.
	 *
	 * @return int|null The author ID, or null for no author restriction.
	 */
	public function get_author_id(): ?int {
		return $this->author_id;
	}

/**
	 * Returns whether posts are limited to a single author.
	 *
	 * @return bool Whether an author restriction is set.
	 */
	public function has_author_filter(): bool {
		return $this->author_id !== null;
	}

/**
	 * Returns the post IDs to limit posts to.
	 *
	 * @return array<int> The post IDs, or an empty array for no restriction.
	 */
	public function get_include_ids(): array {
		return $this->include_ids;
	}

/**
	 * Returns whether posts are limited to specific post IDs.
	 *
	 * @return bool Whether a post ID restriction is set.
	 */
	public function has_include(): bool {
		return $this->include_ids !== [];
	}

/**
	 * Returns the zero-based offset of the requested page.
	 *
	 * @return int The offset.
	 */
	public function get_offset(): int {
		return ( ( $this->page - 1 ) * $this->per_page );
	}
}