404-solution / includes / repositories / RedirectsRepositoryInterface.php

RedirectsRepositoryInterface.php in 404 Solution trunk, at includes/repositories/RedirectsRepositoryInterface.php

156 lines 5.3 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public contract for redirect CRUD, conditions, regex matching, and cleanup operations.
9	*
10	* Extracted from DataAccess in Phase 2 of the DataAccess refactor. Callers that
11	* need redirect lookups, mutations, scheduled cleanup, or condition management
12	* program against this interface.
13	*/
14	interface ABJ_404_Solution_RedirectsRepositoryInterface {
15
16	// =========================================================================
17	// Redirect CRUD (from DataAccessTrait_Redirects)
18	// =========================================================================
19
20	/**
21	* @param int\|string $id
22	* @return void
23	*/
24	public function deleteRedirect($id);
25
26	/**
27	* Fetch manual and regex redirects that are eligible for server-format
28	* export, with destination URLs resolved into the serialized read shape.
29	*
30	* @return array<int, array{source: string, dest: string, code: int, is_regex: bool}>
31	*/
32	public function getExportableRedirects(): array;
33
34	/**
35	* Store a redirect for future use.
36	*
37	* Refactored in queue task c738 (audit source: design-audit-2026-05-29.md,
38	* criterion 220 Interface Size). The previous 8-positional signature
39	* (fromURL, status, type, final_dest, code, disabled, engine, score) had
40	* two transposable URL strings and five overlapping numeric fields; all
41	* those fields are now bundled into {@see ABJ_404_Solution_RedirectSpec}.
42	*
43	* @param ABJ_404_Solution_RedirectSpec $spec
44	* @return int
45	*/
46	public function setupRedirect(ABJ_404_Solution_RedirectSpec $spec);
47
48	/**
49	* Store a redirect only when no row already has its normalized source URL.
50	* The persistence boundary performs the check and insert in one statement.
51	*
52	* @return int New row id, or 0 when the source already exists/write fails.
53	*/
54	public function setupRedirectIfSourceAbsent(ABJ_404_Solution_RedirectSpec $spec): int;
55
56	/**
57	* @param string $url
58	* @param bool $degradedMode
59	* @return array<string, mixed>
60	*/
61	public function getActiveRedirectForURL($url, $degradedMode = false);
62
63	/**
64	* @param string $url
65	* @return array<string, mixed>
66	*/
67	public function getExistingRedirectForURL($url);
68
69	/**
70	* Move redirects with the specified status/type values to trash.
71	*
72	* @param array<int, int\|string> $types
73	* @param string $purgeType
74	* @return array{status: string, rows_affected: int, redirect_types: array<int, int>}
75	*/
76	public function deleteSpecifiedRedirects(array $types, string $purgeType): array;
77
78	// =========================================================================
79	// Redirect conditions (from DataAccessTrait_Redirects)
80	// =========================================================================
81
82	/**
83	* @param int $redirectId
84	* @return array<int, array<string, mixed>>
85	*/
86	public function getRedirectConditions(int $redirectId): array;
87
88	/**
89	* Replace the full condition set for a redirect. The delete + inserts run
90	* inside a single transaction so a mid-replacement DB failure cannot leave
91	* a partial condition set.
92	*
93	* @param int $redirectId
94	* @param array<int, array<string, mixed>> $conditions
95	* @return string Error message on failure ('' on success).
96	*/
97	public function saveRedirectConditions(int $redirectId, array $conditions): string;
98
99	// =========================================================================
100	// Redirect updates (from DataAccessTrait_Stats)
101	// =========================================================================
102
103	/**
104	* Mutate an existing redirect row. Inputs flow through
105	* {@see ABJ_404_Solution_RedirectUpdate}, a typed parameter object that
106	* replaced an eight-argument positional signature so $fromUrl and
107	* $destination (both arbitrary strings) cannot be silently swapped.
108	*
109	* @return string Error message on validation failure, empty string on success.
110	*/
111	public function updateRedirect(ABJ_404_Solution_RedirectUpdate $update): string;
112
113	/**
114	* @param array<int, int\|string> $ids
115	* @return array<int, array<string, mixed>>
116	*/
117	public function getRedirectsByIDs($ids);
118
119	/**
120	* @param int $id
121	* @param string $newstatus
122	* @return string
123	*/
124	public function updateRedirectTypeStatus($id, $newstatus);
125
126	/**
127	* @param int $id
128	* @param int $trash
129	* @return string
130	*/
131	public function moveRedirectsToTrash($id, $trash);
132
133	// =========================================================================
134	// Regex cache (from DataAccess static state)
135	// =========================================================================
136
137	/** @return void */
138	public function clearRegexRedirectsCache(): void;
139
140	// =========================================================================
141	// Static utilities (from DataAccessTrait_Redirects)
142	// =========================================================================
143
144	/**
145	* @param mixed $url
146	* @return string
147	*/
148	public static function computeRedirectsCanonicalUrl($url): string;
149
150	/**
151	* @param string $columnExpr
152	* @return string
153	*/
154	public static function hitsCanonicalUrlSqlExpression(string $columnExpr): string;
155	}
156