@@ -15,16 +15,244 @@ This document provides integration feedback from the wp-sinople-theme WordPress
1515
1616| Issue | Severity | Impact |
1717| -------| ----------| --------|
18+ | PHP 8.1+ blocks WordPress adoption | ** Critical** | WordPress 6.4 supports PHP 7.4+, most hosts still on 7.4/8.0 |
19+ | No WordPress adapter | High | camelCase API vs snake_case WordPress conventions |
1820| Feature set too minimal | Medium | WordPress has equivalent functions already |
1921| No RDF/Turtle escaping | High | Semantic themes require W3C-compliant escaping |
22+ | Limited validators | Medium | Only email/url - missing int(), ip(), domain() |
2023| Missing SPDX license headers | Low | Compliance concern for FOSS projects |
21- | No PHP 8.1+ features | Medium | Missing enums, union types, readonly properties |
2224
2325---
2426
2527## Detailed Recommendations
2628
27- ### 1. Differentiate from WordPress Core Functions
29+ ### 0. CRITICAL: PHP 7.4+ Compatibility Layer
30+
31+ ** Problem** : php-aegis requires PHP 8.1+, but WordPress ecosystem reality:
32+ - WordPress 6.4+ officially supports PHP 7.4+
33+ - Many shared hosts still run PHP 7.4 or 8.0
34+ - Plugin/theme developers must support the WordPress minimum
35+
36+ ** Solution** : Split into two packages:
37+
38+ ```
39+ php-aegis (PHP 8.1+) ← Modern API with enums, union types
40+ │
41+ └── php-aegis-compat (PHP 7.4+) ← Polyfill package for WordPress
42+ ```
43+
44+ ** php-aegis-compat Implementation** :
45+
46+ ``` php
47+ <?php
48+ // SPDX-License-Identifier: MIT
49+ // php-aegis-compat/src/Escape.php
50+
51+ namespace Aegis;
52+
53+ /**
54+ * PHP 7.4+ compatible escape functions.
55+ * Mirrors php-aegis API without 8.1+ features.
56+ */
57+ final class Escape
58+ {
59+ /**
60+ * @param string $value
61+ * @param string $context One of: html, attr, url, js, css, turtle, jsonld
62+ * @return string
63+ */
64+ public static function context(string $value, string $context): string
65+ {
66+ switch ($context) {
67+ case 'html':
68+ return htmlspecialchars($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
69+ case 'attr':
70+ return htmlspecialchars($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
71+ case 'url':
72+ return filter_var($value, FILTER_SANITIZE_URL) ?: '';
73+ case 'turtle':
74+ return Semantic\Turtle::escapeString($value);
75+ default:
76+ throw new \InvalidArgumentException("Unknown context: {$context}");
77+ }
78+ }
79+ }
80+ ```
81+
82+ ** Composer Setup** :
83+ ``` json
84+ {
85+ "name" : " hyperpolymath/php-aegis-compat"
86+ "description" : " PHP 7.4+ compatibility layer for php-aegis"
87+ "require" : {
88+ "php" : " >=7.4"
89+ },
90+ "conflict" : {
91+ "hyperpolymath/php-aegis" : " *"
92+ },
93+ "autoload" : {
94+ "psr-4" : { "Aegis\\ " : " src/"
95+ }
96+ }
97+ ```
98+
99+ ** Usage in WordPress plugins** :
100+ ``` php
101+ // In plugin bootstrap
102+ if (PHP_VERSION_ID >= 80100) {
103+ require_once __DIR__ . '/vendor/hyperpolymath/php-aegis/autoload.php';
104+ } else {
105+ require_once __DIR__ . '/vendor/hyperpolymath/php-aegis-compat/autoload.php';
106+ }
107+ ```
108+
109+ ### 1. WordPress Adapter (snake_case API)
110+
111+ ** Problem** : WordPress uses ` snake_case ` functions, php-aegis uses ` CamelCase ` methods.
112+
113+ ** Solution** : Provide WordPress adapter functions:
114+
115+ ``` php
116+ <?php
117+ // SPDX-License-Identifier: MIT
118+ // php-aegis/src/WordPress/functions.php
119+
120+ namespace Aegis\WordPress;
121+
122+ use Aegis\Escape;
123+ use Aegis\Validate;
124+ use Aegis\Semantic\Turtle;
125+
126+ /**
127+ * WordPress-style function wrappers.
128+ * Use in themes/plugins for familiar API.
129+ */
130+
131+ function aegis_escape_html(string $value): string {
132+ return Escape::html($value);
133+ }
134+
135+ function aegis_escape_attr(string $value): string {
136+ return Escape::attr($value);
137+ }
138+
139+ function aegis_escape_turtle(string $value): string {
140+ return Turtle::escapeString($value);
141+ }
142+
143+ function aegis_escape_turtle_iri(string $iri): string {
144+ return Turtle::escapeIRI($iri);
145+ }
146+
147+ function aegis_validate_int($value): ?int {
148+ return Validate::int($value);
149+ }
150+
151+ function aegis_validate_ip(string $value): ?string {
152+ return Validate::ip($value);
153+ }
154+
155+ function aegis_validate_domain(string $value): ?string {
156+ return Validate::domain($value);
157+ }
158+ ```
159+
160+ ** Registration via WordPress hooks** :
161+ ``` php
162+ <?php
163+ // php-aegis/src/WordPress/Loader.php
164+
165+ namespace Aegis\WordPress;
166+
167+ final class Loader
168+ {
169+ public static function init(): void
170+ {
171+ // Load function wrappers
172+ require_once __DIR__ . '/functions.php';
173+
174+ // Register with WordPress security hooks
175+ add_filter('sanitize_text_field', [self::class, 'enhanceSanitize'], 10, 1);
176+ }
177+
178+ public static function enhanceSanitize(string $value): string
179+ {
180+ // Aegis-enhanced sanitization
181+ return \Aegis\Sanitize::text($value);
182+ }
183+ }
184+
185+ // Auto-init when WordPress is detected
186+ if (defined('ABSPATH')) {
187+ add_action('plugins_loaded', [Loader::class, 'init']);
188+ }
189+ ```
190+
191+ ### 2. Extended Validators
192+
193+ ** Problem** : Only ` email() ` and ` url() ` validators exist. Real-world needs:
194+
195+ ** Add these validators** :
196+
197+ ``` php
198+ <?php
199+ // SPDX-License-Identifier: MIT
200+
201+ namespace Aegis;
202+
203+ final class Validate
204+ {
205+ public static function email(string $value): ?string { /* existing */ }
206+ public static function url(string $value): ?string { /* existing */ }
207+
208+ // NEW validators:
209+
210+ public static function int(mixed $value): ?int
211+ {
212+ if (is_int($value)) return $value;
213+ if (is_string($value) && ctype_digit(ltrim($value, '-'))) {
214+ return (int)$value;
215+ }
216+ return null;
217+ }
218+
219+ public static function ip(string $value, int $flags = FILTER_FLAG_IPV4 | FILTER_FLAG_IPV6): ?string
220+ {
221+ $result = filter_var($value, FILTER_VALIDATE_IP, $flags);
222+ return $result !== false ? $result : null;
223+ }
224+
225+ public static function domain(string $value): ?string
226+ {
227+ // Remove protocol if present
228+ $domain = preg_replace('#^https?://#', '', $value);
229+ $domain = explode('/', $domain)[0];
230+
231+ if (filter_var($domain, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)) {
232+ return $domain;
233+ }
234+ return null;
235+ }
236+
237+ public static function uuid(string $value): ?string
238+ {
239+ if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $value)) {
240+ return strtolower($value);
241+ }
242+ return null;
243+ }
244+
245+ public static function slug(string $value): ?string
246+ {
247+ if (preg_match('/^[a-z0-9]+(?:-[a-z0-9]+)*$/', $value)) {
248+ return $value;
249+ }
250+ return null;
251+ }
252+ }
253+ ```
254+
255+ ### 3. Differentiate from WordPress Core Functions
28256
29257** Problem** : WordPress already provides ` esc_html() ` , ` esc_attr() ` , ` sanitize_text_field() ` , etc.
30258
@@ -282,20 +510,26 @@ We will add support in sanctify-php to:
282510
283511## Action Items for php-aegis Team
284512
285- ### Priority 1 (High)
513+ ### Priority 0 (Critical) — Adoption Blockers
514+ - [ ] Create ` php-aegis-compat ` package for PHP 7.4+
515+ - [ ] Add WordPress adapter with snake_case functions
516+ - [ ] Extend ` Validate ` class: ` int() ` , ` ip() ` , ` domain() ` , ` uuid() ` , ` slug() `
517+
518+ ### Priority 1 (High) — Unique Value
286519- [ ] Add ` Aegis\Semantic\Turtle ` namespace with W3C-compliant escaping
287520- [ ] Add ` Aegis\IndieWeb\Micropub ` for content sanitization
288521- [ ] Add SPDX headers to all files
289522
290- ### Priority 2 (Medium)
291- - [ ] Refactor to use PHP 8.1+ enums for contexts
523+ ### Priority 2 (Medium) — Polish
524+ - [ ] Use PHP 8.1+ enums for contexts (in main package only)
292525- [ ] Add union types throughout API
293526- [ ] Document differentiation from WordPress core functions
527+ - [ ] Auto-detect WordPress and register hooks
294528
295- ### Priority 3 (Low)
529+ ### Priority 3 (Low) — Extended Features
296530- [ ] Add ActivityPub sanitization support
297531- [ ] Add JSON-LD validation
298- - [ ] Create WordPress integration hooks
532+ - [ ] Laravel adapter (in addition to WordPress)
299533
300534---
301535
0 commit comments