<?php
/**
 * A plugin whose SEO data can be imported.
 *
 * @package ElevenRank
 * @since   1.0.0
 */

namespace ElevenRank\Modules\Import;

defined( 'ABSPATH' ) || exit;

/**
 * A source reads another plugin's stored data and describes it in ElevenRank's terms. It never
 * writes anything and never calls the other plugin's code: it only reads what that plugin left in
 * the database (post, term and user meta, options and tables), whether or not the plugin is active.
 *
 * Records use ElevenRank's meta keys (see `Keys`) as field names, with values already cleaned up:
 * templates have their variables converted, robots directives are an array of flags, keywords a list.
 *
 * @since 1.0.0
 */
interface Source {

	/**
	 * Short id, such as `yoast`.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function id(): string;

	/**
	 * Name of the plugin, for the importer screen.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function label(): string;

	/**
	 * Whether the plugin has left data that can be imported.
	 *
	 * @since 1.0.0
	 *
	 * @return bool
	 */
	public function detected(): bool;

	/**
	 * Whether the plugin is active right now.
	 *
	 * @since 1.0.0
	 *
	 * @return bool
	 */
	public function is_active(): bool;

	/**
	 * What there is to import.
	 *
	 * @since 1.0.0
	 *
	 * @return array{posts: int, terms: int, authors: int, redirects: int, settings: bool}
	 */
	public function counts(): array;

	/**
	 * A batch of posts that have SEO data, in id order.
	 *
	 * @since 1.0.0
	 *
	 * @param int $after Only posts with a higher id.
	 * @param int $limit Most posts to return.
	 * @return array<int, array{id: int, fields: array<string, mixed>, notes: string[]}> Records by post id.
	 */
	public function posts( int $after, int $limit ): array;

	/**
	 * A batch of terms that have SEO data, in term id order.
	 *
	 * @since 1.0.0
	 *
	 * @param int $after Only terms with a higher id.
	 * @param int $limit Most terms to return.
	 * @return array<int, array{id: int, fields: array<string, mixed>, notes: string[]}>
	 */
	public function terms( int $after, int $limit ): array;

	/**
	 * A batch of authors that have SEO data, in user id order.
	 *
	 * @since 1.0.0
	 *
	 * @param int $after Only users with a higher id.
	 * @param int $limit Most users to return.
	 * @return array<int, array{id: int, fields: array<string, mixed>, notes: string[]}>
	 */
	public function authors( int $after, int $limit ): array;

	/**
	 * The site-wide settings that map onto ElevenRank's: titles and descriptions, robots defaults,
	 * the separator, social profiles and the identity of the site.
	 *
	 * @since 1.0.0
	 *
	 * @return array{settings: array<string, array<string, mixed>>, notes: string[]} Values by settings group.
	 */
	public function settings(): array;

	/**
	 * Redirects the plugin keeps in a readable table, option or post type.
	 *
	 * @since 1.0.0
	 *
	 * @param int $after  Only redirects with a higher id.
	 * @param int $limit  Most redirects to return.
	 * @return array<int, array{id: int, rules: array<int, array<string, mixed>>, notes: string[]}> By the plugin's own id; each record has the rules that come from it (a plugin may keep several sources in one redirect), in the shape `Rule_Validator` takes: source, destination, type, match_type, status.
	 */
	public function redirects( int $after, int $limit ): array;
}