thinkrank / includes / seo / interfaces / class-seo-manager-interface.php

class-seo-manager-interface.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 2.4.0, at includes/seo/interfaces/class-seo-manager-interface.php

213 lines 7.4 KB

Raw Download Zip

1	<?php
2	/**
3	* SEO Manager Interface
4	*
5	* Defines the contract for all SEO management classes in ThinkRank.
6	* This interface ensures consistent patterns across all SEO functionality
7	* including schema generation, social meta, robots meta, and site-wide settings.
8	*
9	* @package ThinkRank
10	* @subpackage SEO\Interfaces
11	* @since 1.0.0
12	*/
13
14	declare(strict_types=1);
15
16	namespace ThinkRank\SEO\Interfaces;
17
18	// Prevent direct access
19	if (!defined('ABSPATH')) {
20	exit;
21	}
22
23	/**
24	* SEO Manager Interface
25	*
26	* Universal interface for all SEO management classes providing consistent
27	* CRUD operations, validation, and output generation across different contexts
28	* (site-wide, per-post, per-page, etc.).
29	*
30	* @since 1.0.0
31	*/
32	interface SEO_Manager_Interface {
33
34	/**
35	* Get SEO settings for a specific context
36	*
37	* Retrieves SEO settings based on context type and optional context ID.
38	* Context types include 'site', 'post', 'page', 'product', etc.
39	* Context ID is null for site-wide settings, post ID for per-post settings.
40	*
41	* @since 1.0.0
42	*
43	* @param string $context_type The context type ('site', 'post', 'page', 'product')
44	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
45	* @return array SEO settings array with standardized structure
46	*/
47	public function get_settings(string $context_type, ?int $context_id = null): array;
48
49	/**
50	* Save SEO settings for a specific context
51	*
52	* Saves SEO settings with proper validation and sanitization.
53	* Automatically handles context-specific logic and database operations.
54	*
55	* @since 1.0.0
56	*
57	* @param string $context_type The context type ('site', 'post', 'page', 'product')
58	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
59	* @param array $settings Settings array to save
60	* @return bool True on success, false on failure
61	*/
62	public function save_settings(string $context_type, ?int $context_id, array $settings): bool;
63
64	/**
65	* Validate SEO settings
66	*
67	* Validates settings array according to context-specific rules.
68	* Returns validation results with errors, warnings, and suggestions.
69	*
70	* @since 1.0.0
71	*
72	* @param array $settings Settings array to validate
73	* @return array Validation results with 'valid', 'errors', 'warnings', 'suggestions' keys
74	*/
75	public function validate_settings(array $settings): array;
76
77	/**
78	* Get output data for frontend rendering
79	*
80	* Generates the final output data for frontend meta tags, schema markup,
81	* or other SEO elements based on context and settings.
82	*
83	* @since 1.0.0
84	*
85	* @param string $context_type The context type ('site', 'post', 'page', 'product')
86	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
87	* @return array Output data ready for frontend rendering
88	*/
89	public function get_output_data(string $context_type, ?int $context_id): array;
90
91	/**
92	* Get supported context types
93	*
94	* Returns array of context types supported by this SEO manager.
95	* Different managers may support different contexts.
96	*
97	* @since 1.0.0
98	*
99	* @return array Array of supported context types
100	*/
101	public function get_supported_contexts(): array;
102
103	/**
104	* Get default settings for a context type
105	*
106	* Returns default settings structure for the specified context type.
107	* Used for initialization and fallback values.
108	*
109	* @since 1.0.0
110	*
111	* @param string $context_type The context type to get defaults for
112	* @return array Default settings array
113	*/
114	public function get_default_settings(string $context_type): array;
115
116	/**
117	* Delete settings for a specific context
118	*
119	* Removes all settings for the specified context.
120	* Used for cleanup operations and reset functionality.
121	*
122	* @since 1.0.0
123	*
124	* @param string $context_type The context type ('site', 'post', 'page', 'product')
125	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
126	* @return bool True on success, false on failure
127	*/
128	public function delete_settings(string $context_type, ?int $context_id): bool;
129
130	/**
131	* Check if settings exist for a context
132	*
133	* Determines whether settings have been configured for the specified context.
134	* Useful for conditional logic and fallback handling.
135	*
136	* @since 1.0.0
137	*
138	* @param string $context_type The context type ('site', 'post', 'page', 'product')
139	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
140	* @return bool True if settings exist, false otherwise
141	*/
142	public function has_settings(string $context_type, ?int $context_id): bool;
143
144	/**
145	* Get settings schema definition
146	*
147	* Returns the schema definition for settings validation and form generation.
148	* Includes field types, validation rules, and UI configuration.
149	*
150	* @since 1.0.0
151	*
152	* @param string $context_type The context type to get schema for
153	* @return array Settings schema definition
154	*/
155	public function get_settings_schema(string $context_type): array;
156
157	/**
158	* Bulk update settings
159	*
160	* Updates multiple settings efficiently in a single operation.
161	* Useful for import/export and batch operations.
162	*
163	* @since 1.0.0
164	*
165	* @param array $bulk_settings Array of settings keyed by context_type:context_id
166	* @return array Results array with success/failure status for each update
167	*/
168	public function bulk_update_settings(array $bulk_settings): array;
169
170	/**
171	* Get settings history
172	*
173	* Returns revision history for settings changes.
174	* Useful for audit trails and rollback functionality.
175	*
176	* @since 1.0.0
177	*
178	* @param string $context_type The context type ('site', 'post', 'page', 'product')
179	* @param int\|null $context_id Optional. Context ID (null for site-wide, post ID for per-post)
180	* @param int $limit Optional. Number of revisions to return (default: 10)
181	* @return array Array of settings revisions with timestamps and user info
182	*/
183	public function get_settings_history(string $context_type, ?int $context_id, int $limit = 10): array;
184
185	/**
186	* Export settings
187	*
188	* Exports settings in a standardized format for backup or migration.
189	* Includes metadata and version information.
190	*
191	* @since 1.0.0
192	*
193	* @param string $context_type Optional. Context type to export (null for all)
194	* @param int\|null $context_id Optional. Context ID to export (null for all in context_type)
195	* @return array Exported settings with metadata
196	*/
197	public function export_settings(?string $context_type = null, ?int $context_id = null): array;
198
199	/**
200	* Import settings
201	*
202	* Imports settings from exported data with validation and conflict resolution.
203	* Supports partial imports and merge strategies.
204	*
205	* @since 1.0.0
206	*
207	* @param array $import_data Exported settings data
208	* @param array $options Import options (merge_strategy, validate, etc.)
209	* @return array Import results with success/failure details
210	*/
211	public function import_settings(array $import_data, array $options = []): array;
212	}
213