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 1.0.0, at includes/seo/interfaces/class-seo-manager-interface.php

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