bryzgalov/wp-multi-city
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

spec(wpmc S3): design doc for shortcode_dmr + helpers

Browse Source
This commit is contained in:
Vladimir Bryzgalov
2026-05-12 19:36:00 +05:00
parent 12a271981a
commit 245c114ec3
1 changed files with 220 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-05-12-s3-shortcode-dmr-helpers-design.md
+220
View File
@@ -0,0 +1,220 @@
# S3 — `[shortcode_dmr]` + хелперы `wpmc_current_town` / `wpmc_alt_get_field` / `wpmc_remove_domain_link` / `wpmc_get_term_by_slug`
- Beads: `cp-arq` (parent epic `cp-cw4`)
- Depends on: `cp-q7g` (S2 — taxonomy `town` + CPT `shortcode-town` + ACF `list_shortcode`, закрыт)
- Blocks: `cp-83m` (S4 — URL-роутер `/{city}/{path}/`)
- Дата: 2026-05-12
## Цель
Ядро подстановки контента по городу. Тема вызывает четыре публичные wpmc-функции и шорткод `[shortcode_dmr id=N]`; плагин разрешает значение для текущего города из ACF-репитера `list_shortcode` поста-контейнера.
Версия S3 не зависит от URL-роутера (S4) — `current_town()` работает через парсинг `REQUEST_URI` напрямую. S4 потом подключит свою query-var логику через фильтр `wpmc_current_town_slug`.
## Архитектура
```
includes/
├── class-helpers.php ← WPMultiCity\Helpers
├── class-shortcode-dmr.php ← WPMultiCity\ShortcodeDmr
└── wpmc-functions.php ← процедурный API (тонкие обёртки)
wp-multi-city.php ← require_once wpmc-functions.php (unconditional)
includes/class-plugin.php ← boot() добавляет ShortcodeDmr::register()
```
`Helpers` — статический класс с методами реализации. `ShortcodeDmr` — статический класс с `register()` (вешает `add_shortcode` на init) и handler-методом. `wpmc-functions.php` — глобальные функции `wpmc_*`, каждая в одну строку вызывает соответствующий метод `Helpers`.
Загрузка процедурного API — безусловно в главном файле плагина (до проверки ACF), чтобы `function_exists('wpmc_current_town')` в шаблонах темы всегда возвращал `true`.
## Публичный API
```php
function wpmc_current_town(): ?string;
function wpmc_get_term_by_slug(string $slug, string $taxonomy = 'town'): ?WP_Term;
function wpmc_alt_get_field(string $selector, $post_id = false, bool $format_value = true);
function wpmc_remove_domain_link(string $url): string;
```
Shortcode: `[shortcode_dmr id=N]`.
## `Helpers::current_town(): ?string`
Логика:
1. Per-request memoization — если уже определено, вернуть закэшированное.
2. Распарсить `$_SERVER['REQUEST_URI']`: разбить по `/`, отбросить пустые сегменты, взять первый.
3. Если первый сегмент совпадает со slug существующего term'а `town` (через `get_terms('town', ['fields' => 'id=>slug', 'hide_empty' => false])`) → resolved = этот slug.
4. Иначе → resolved = `apply_filters('wpmc_main_town_slug', null)` (тема выставляет дефолт).
5. `resolved = apply_filters('wpmc_current_town_slug', $resolved)` — extension-point для S4.
6. Сохранить в memo, вернуть.
Возвращает `null` если ни один из шагов 3-5 не дал значение (т.е. URI не совпадает с термом, фильтры пусты).
## `Helpers::get_term_by_slug(string $slug, string $taxonomy = 'town'): ?WP_Term`
```php
private static array $term_cache = [];
public static function get_term_by_slug(string $slug, string $taxonomy = 'town'): ?WP_Term
{
$key = $taxonomy . '|' . $slug;
if (array_key_exists($key, self::$term_cache)) {
return self::$term_cache[$key];
}
$term = get_term_by('slug', $slug, $taxonomy);
return self::$term_cache[$key] = ($term instanceof \WP_Term) ? $term : null;
}
```
## `ShortcodeDmr` — handler `[shortcode_dmr id=N]`
```
1. shortcode_atts(['id' => 0], $atts); $id = (int) $atts['id']; if ($id <= 0) return '';
2. $town = Helpers::current_town(); if ($town === null) return '';
3. $term = Helpers::get_term_by_slug($town); if ($term === null) return '';
4. Per-request cache key = $id . '|' . $town. Если есть — вернуть.
5. $rows = get_field('list_shortcode', $id); if (empty($rows) || !is_array($rows)) cache and return ''.
6. foreach ($rows as $row): if ((int) $row['town'] === $term->term_id) { result = (string) $row['text']; break; }
7. Save to cache and return.
```
Регистрация: `add_action('init', [self::class, 'do_register'])` → внутри `add_shortcode('shortcode_dmr', [self::class, 'render'])`.
## `Helpers::alt_get_field($selector, $post_id, $format_value)`
```php
public static function alt_get_field(string $selector, $post_id = false, bool $format_value = true)
{
$post_id = apply_filters('wpmc_alt_get_field_post_id', $post_id, $selector);
if (!function_exists('get_field')) {
return null;
}
$value = get_field($selector, $post_id, $format_value);
return is_string($value) ? do_shortcode($value) : $value;
}
```
S4 подключит свой фильтр `wpmc_alt_get_field_post_id` для clone→original маппинга. В S3 фильтр без подписчиков — `$post_id` передаётся через `get_field` без изменений.
`function_exists('get_field')` guard — на случай если ACF деактивирован после загрузки темы.
## `Helpers::remove_domain_link(string $url): string`
```php
public static function remove_domain_link(string $url): string
{
$parsed = parse_url($url);
if ($parsed === false || empty($parsed['scheme'])) {
return $url;
}
$scheme = strtolower($parsed['scheme']);
if ($scheme !== 'http' && $scheme !== 'https') {
return $url;
}
$path = $parsed['path'] ?? '';
$query = isset($parsed['query']) ? '?' . $parsed['query'] : '';
$fragment = isset($parsed['fragment']) ? '#' . $parsed['fragment'] : '';
return $path . $query . $fragment;
}
```
Поведение:
- `https://site.com/foo/bar/` → `/foo/bar/`
- `http://site.com/foo?q=1#a` → `/foo?q=1#a`
- `/foo/bar/` (без schemе) → `/foo/bar/` (no-op)
- `mailto:x@y.com` → `mailto:x@y.com` (no-op)
- `tel:+79991234567` → `tel:+79991234567` (no-op)
## Plugin::boot() — изменение
После S2-регистраций (Taxonomy/PostType/FieldGroup) добавить:
```php
ShortcodeDmr::register();
```
`Helpers` сам по себе не регистрирует никаких хуков — это статический utility-класс.
## wp-multi-city.php — изменение
Добавить:
```php
require_once WPMC_PLUGIN_DIR . 'includes/wpmc-functions.php';
```
После строки с `register_autoloader()` и до `plugins_loaded` add_action. Безусловно — функции должны быть доступны теме даже если ACF отсутствует.
## Тестовый стек
PHPUnit 9.6 + Brain Monkey 2.7 + Mockery 1.6 + Patchwork (уже настроены в S2).
Дополнительно в `tests/TestCase.php::setUp()` после `Monkey\setUp()`:
```php
\WPMultiCity\Helpers::reset_cache();
\WPMultiCity\ShortcodeDmr::reset_cache();
```
Каждый класс выставит публичный `reset_cache()` метод (только для тестов; не используется в production-коде, но не помечается @internal — это легитимная точка очистки).
`patchwork.json` уже разрешает редефайн `function_exists` (нужен для теста `alt_get_field` без ACF).
## Тестовые сценарии
`tests/HelpersTest.php`:
1. `current_town`: REQUEST_URI=`/tyumen/`, term `tyumen` exists → `'tyumen'`.
2. `current_town`: REQUEST_URI=`/something-not-a-city/`, нет main_town filter → `null`.
3. `current_town`: REQUEST_URI=`/`, filter `wpmc_main_town_slug` → `'spb'` → `'spb'`.
4. `current_town`: REQUEST_URI=`/tyumen/`, term `tyumen` exists, main_town=`'spb'` → `'tyumen'` (URI выигрывает).
5. `current_town`: фильтр `wpmc_current_town_slug` перекрывает результат → `'override'`.
6. `current_town`: per-request memo — второй вызов не зовёт `get_terms` повторно.
7. `get_term_by_slug`: первый вызов вызывает `get_term_by`, второй — нет (cache).
8. `get_term_by_slug`: term не найден → `null` (и null закэширован).
9. `alt_get_field`: string value → `do_shortcode` применён.
10. `alt_get_field`: array value → возвращён без `do_shortcode`.
11. `alt_get_field`: фильтр `wpmc_alt_get_field_post_id` подменяет $post_id.
12. `alt_get_field`: `function_exists('get_field')` false → `null`.
13. `remove_domain_link`: `https://site.com/foo/` → `/foo/`.
14. `remove_domain_link`: `https://site.com/foo?q=1#a` → `/foo?q=1#a`.
15. `remove_domain_link`: `/foo/` → `/foo/` (no-op).
16. `remove_domain_link`: `mailto:x@y` → `mailto:x@y` (no-op).
17. `remove_domain_link`: невалидный URL → возвращает как есть.
`tests/ShortcodeDmrTest.php`:
18. `register` вешает `init` action с `do_register`.
19. `do_register` вызывает `add_shortcode('shortcode_dmr', ...)`.
20. `render` с id=0 → `''`.
21. `render` когда `current_town()` = null → `''`.
22. `render` когда term не найден → `''`.
23. `render` когда rows = [] → `''`.
24. `render` когда matching row → возвращает `text`.
25. `render` когда no matching row → `''`.
26. `render` — второй вызов с теми же $atts → не зовёт `get_field` повторно (cache).
`tests/PluginBootShortcodeDmrTest.php`:
27. `Plugin::boot()` вешает `ShortcodeDmr::do_register` на init.
Финал: 27 новых тестов + 9 предыдущих = 36 тестов суммарно.
## Acceptance verification (после green-тестов)
1. `vendor/bin/phpunit` → 36 тестов зелёные, 0 risky/warning.
2. Активировать плагин на чистом WP с ACF Pro + темой, в которой шаблон вызывает `wpmc_current_town()` и `[shortcode_dmr id=42]`.
3. Создать таксон `town` со slug'ами `spb`, `tyumen`.
4. Создать `shortcode-town` пост ID=42 с одной строкой `list_shortcode`: town=`tyumen`, text=`Тюмень-текст`.
5. Открыть `/tyumen/` → шорткод должен отдать `Тюмень-текст`. Открыть `/` → `''` (без filter'а). С `add_filter('wpmc_main_town_slug', fn() => 'spb')` и второй row town=`spb`, text=`СПб-текст` → `/` отдаёт `СПб-текст`.
## Что НЕ входит в S3
- query-var `town` и URL-роутер `/{city}/{path}/` — S4 (cp-83m).
- `page_unic` / clone-to-original mapping — S4.
- Yoast/CF7/sitemap фильтры — out of MVP.
- Admin UI / settings page для main_town slug — используем фильтр.
## Open questions
Нет. Все решения зафиксированы.