feat: declarative and operation-based menu item editing
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7
This commit is contained in:
Claude Opus 5.5
@@ -0,0 +1,418 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace LIT\MCP\Integrations\WordPress\Menus;
|
||||
|
||||
use LIT\MCP\Abilities\WriteFailed;
|
||||
use RuntimeException;
|
||||
use Throwable;
|
||||
use WP_Post;
|
||||
use WP_Term;
|
||||
|
||||
/**
|
||||
* Validates a desired menu tree against the current items and writes it.
|
||||
*
|
||||
* Node shape = the lit/menu-get node (P4 ruling): an existing item is identified by
|
||||
* its id alone; type/object/object_id and – for post/taxonomy items – url are
|
||||
* informational and ignored. Existing items keep all their data (classes, target,
|
||||
* description, custom label, …); title only becomes a custom label when it differs
|
||||
* from the currently shown title, url only changes for custom items.
|
||||
*
|
||||
* apply() is all-or-nothing as far as WordPress allows: on a failure it deletes the
|
||||
* items it created and rewrites the touched items with their previous data. Deleted
|
||||
* menu items cannot be restored with their IDs, so a failure after a deletion is a
|
||||
* partial write. Not final so the ability can be tested with a mock.
|
||||
*/
|
||||
class MenuWriter
|
||||
{
|
||||
private const NON_LINKABLE = ['revision', 'nav_menu_item', 'attachment'];
|
||||
private const URL_SCHEMES = ['http', 'https', 'mailto', 'tel'];
|
||||
private const URL_RULE = '/pfad, #anker, http(s), mailto, tel';
|
||||
|
||||
/** @var list<int> Items created by the running apply(). */
|
||||
private array $created = [];
|
||||
|
||||
/** @var list<int> Existing items rewritten by the running apply(). */
|
||||
private array $touched = [];
|
||||
|
||||
/** @var list<int> Items deleted by the running apply(). */
|
||||
private array $deleted = [];
|
||||
|
||||
/**
|
||||
* @param list<mixed> $tree
|
||||
* @param array<int, object> $current Current items by ID.
|
||||
* @return array{
|
||||
* errors: array<string, string>,
|
||||
* removals: list<array{id: int, title: string}>,
|
||||
* warnings: list<string>
|
||||
* }
|
||||
*/
|
||||
public function plan(array $tree, array $current): array
|
||||
{
|
||||
$errors = [];
|
||||
$warnings = [];
|
||||
$seen = [];
|
||||
$this->validateNodes($tree, 'items', $current, $seen, $errors, $warnings);
|
||||
|
||||
$removals = [];
|
||||
foreach ($current as $id => $item) {
|
||||
if (! isset($seen[$id])) {
|
||||
$removals[] = ['id' => (int) $id, 'title' => (string) $item->title];
|
||||
}
|
||||
}
|
||||
|
||||
return ['errors' => $errors, 'removals' => $removals, 'warnings' => $warnings];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param list<array<string, mixed>> $tree Validated by plan().
|
||||
* @param array<int, object> $current Current items by ID, in menu order.
|
||||
* @return array{created: int, updated: int, removed: int}
|
||||
* @throws WriteFailed When saving failed; rolledBack tells whether the previous tree was restored.
|
||||
*/
|
||||
public function apply(int $menuId, array $tree, array $current): array
|
||||
{
|
||||
$this->created = [];
|
||||
$this->touched = [];
|
||||
$this->deleted = [];
|
||||
|
||||
try {
|
||||
$position = 0;
|
||||
$seen = [];
|
||||
$this->writeNodes($menuId, $tree, 0, $current, $position, $seen);
|
||||
|
||||
foreach (array_keys($current) as $id) {
|
||||
if (! isset($seen[$id])) {
|
||||
$this->remove((int) $id);
|
||||
}
|
||||
}
|
||||
} catch (Throwable $e) {
|
||||
$this->fail($menuId, $current, $e);
|
||||
}
|
||||
|
||||
return [
|
||||
'created' => count($this->created),
|
||||
'updated' => count($this->touched),
|
||||
'removed' => count($this->deleted),
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<int, object> $current
|
||||
* @param array<int, true> $seen
|
||||
* @param array<string, string> $errors
|
||||
* @param list<string> $warnings
|
||||
*/
|
||||
private function validateNodes(
|
||||
mixed $nodes,
|
||||
string $path,
|
||||
array $current,
|
||||
array &$seen,
|
||||
array &$errors,
|
||||
array &$warnings
|
||||
): void {
|
||||
if (! is_array($nodes) || ! array_is_list($nodes)) {
|
||||
$errors[$path] = 'Liste erwartet.';
|
||||
return;
|
||||
}
|
||||
|
||||
foreach ($nodes as $index => $node) {
|
||||
$nodePath = $path . '.' . $index;
|
||||
if (! is_array($node)) {
|
||||
$errors[$nodePath] = 'Objekt erwartet.';
|
||||
continue;
|
||||
}
|
||||
|
||||
$error = self::isExisting($node)
|
||||
? $this->checkExisting($node, $current, $seen)
|
||||
: $this->checkNew($node, $warnings);
|
||||
if ($error !== null) {
|
||||
$errors[$nodePath] = $error;
|
||||
}
|
||||
|
||||
if (array_key_exists('children', $node)) {
|
||||
$this->validateNodes($node['children'], $nodePath . '.children', $current, $seen, $errors, $warnings);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** @param array<string, mixed> $node A node without id (or id 0/null) is a new item. */
|
||||
private static function isExisting(array $node): bool
|
||||
{
|
||||
return isset($node['id']) && $node['id'] !== 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $node
|
||||
* @param array<int, object> $current
|
||||
* @param array<int, true> $seen
|
||||
*/
|
||||
private function checkExisting(array $node, array $current, array &$seen): ?string
|
||||
{
|
||||
$id = $node['id'];
|
||||
if (! is_int($id) || ! isset($current[$id])) {
|
||||
return 'id ist kein Eintrag dieses Menüs (für neue Einträge id weglassen).';
|
||||
}
|
||||
|
||||
if (isset($seen[$id])) {
|
||||
return sprintf('Eintrag %d kommt mehrfach vor.', $id);
|
||||
}
|
||||
$seen[$id] = true;
|
||||
|
||||
if (array_key_exists('title', $node) && ! is_string($node['title'])) {
|
||||
return 'title muss Text sein.';
|
||||
}
|
||||
|
||||
// P4: url of post/taxonomy items is derived by WordPress – informational, ignored.
|
||||
if ((string) $current[$id]->type === 'custom' && $this->urlChanges($node, $current[$id])) {
|
||||
return $this->validUrl($node['url']) ? null : 'Ungültige url (erlaubt: ' . self::URL_RULE . ').';
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $node
|
||||
* @param list<string> $warnings
|
||||
*/
|
||||
private function checkNew(array $node, array &$warnings): ?string
|
||||
{
|
||||
if (array_key_exists('title', $node) && ! is_string($node['title'])) {
|
||||
return 'title muss Text sein.';
|
||||
}
|
||||
|
||||
$objectId = $node['object_id'] ?? null;
|
||||
|
||||
switch ($node['type'] ?? null) {
|
||||
case 'post':
|
||||
$post = is_int($objectId) ? get_post($objectId) : null;
|
||||
// Same answer for "missing" and "not readable": no probing of private posts via menus.
|
||||
if (
|
||||
! $post instanceof WP_Post
|
||||
|| in_array($post->post_type, self::NON_LINKABLE, true)
|
||||
|| ! current_user_can('read_post', $objectId)
|
||||
) {
|
||||
return 'object_id muss ein vorhandener, für dich lesbarer Eintrag sein.';
|
||||
}
|
||||
if ($post->post_status !== 'publish') {
|
||||
$warnings[] = sprintf(
|
||||
'"%s" ist nicht veröffentlicht und erscheint erst nach dem Veröffentlichen im Menü.',
|
||||
$post->post_title
|
||||
);
|
||||
}
|
||||
return null;
|
||||
case 'taxonomy':
|
||||
$term = is_int($objectId) ? get_term($objectId) : null;
|
||||
return $term instanceof WP_Term
|
||||
&& (is_taxonomy_viewable($term->taxonomy) || current_user_can('edit_term', $objectId))
|
||||
? null
|
||||
: 'object_id muss ein vorhandener, für dich lesbarer Begriff sein.';
|
||||
case 'custom':
|
||||
if (! $this->validUrl($node['url'] ?? null)) {
|
||||
return 'Individueller Link braucht eine gültige url (' . self::URL_RULE . ').';
|
||||
}
|
||||
return is_string($node['title'] ?? null) && trim($node['title']) !== ''
|
||||
? null
|
||||
: 'Individueller Link braucht einen title.';
|
||||
default:
|
||||
return 'type muss post, taxonomy oder custom sein.';
|
||||
}
|
||||
}
|
||||
|
||||
/** @param array<string, mixed> $node */
|
||||
private function urlChanges(array $node, object $item): bool
|
||||
{
|
||||
return array_key_exists('url', $node) && $node['url'] !== (string) $item->url;
|
||||
}
|
||||
|
||||
/** @param array<string, mixed> $node */
|
||||
private function titleChanges(array $node, object $item): bool
|
||||
{
|
||||
return isset($node['title']) && (string) $node['title'] !== (string) $item->title;
|
||||
}
|
||||
|
||||
private function validUrl(mixed $url): bool
|
||||
{
|
||||
if (! is_string($url) || $url === '' || preg_match('/\s/', $url) === 1) {
|
||||
return false;
|
||||
}
|
||||
|
||||
if (str_starts_with($url, '/') || str_starts_with($url, '#')) {
|
||||
return ! str_starts_with($url, '//');
|
||||
}
|
||||
|
||||
$scheme = wp_parse_url($url, PHP_URL_SCHEME);
|
||||
|
||||
return is_string($scheme) && in_array(strtolower($scheme), self::URL_SCHEMES, true);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param list<array<string, mixed>> $nodes
|
||||
* @param array<int, object> $current
|
||||
* @param array<int, true> $seen
|
||||
*/
|
||||
private function writeNodes(
|
||||
int $menuId,
|
||||
array $nodes,
|
||||
int $parentId,
|
||||
array $current,
|
||||
int &$position,
|
||||
array &$seen
|
||||
): void {
|
||||
foreach ($nodes as $node) {
|
||||
$position++;
|
||||
$existing = self::isExisting($node) ? $current[(int) $node['id']] : null;
|
||||
$args = $existing !== null ? $this->argsFromItem($existing) : $this->argsFromNode($node);
|
||||
if ($existing === null ? isset($node['title']) : $this->titleChanges($node, $existing)) {
|
||||
$args['menu-item-title'] = (string) $node['title'];
|
||||
}
|
||||
if ($existing === null ? $node['type'] === 'custom' : $this->customUrlChanges($node, $existing)) {
|
||||
$args['menu-item-url'] = esc_url_raw((string) $node['url']);
|
||||
}
|
||||
$args['menu-item-parent-id'] = $parentId;
|
||||
$args['menu-item-position'] = $position;
|
||||
$args['menu-item-status'] = 'publish';
|
||||
|
||||
$itemId = $this->save($menuId, $existing !== null ? (int) $existing->ID : 0, $args);
|
||||
if ($existing !== null) {
|
||||
$seen[(int) $existing->ID] = true;
|
||||
$this->touched[] = (int) $existing->ID;
|
||||
} else {
|
||||
$this->created[] = $itemId;
|
||||
}
|
||||
|
||||
$this->writeNodes($menuId, (array) ($node['children'] ?? []), $itemId, $current, $position, $seen);
|
||||
}
|
||||
}
|
||||
|
||||
/** @param array<string, mixed> $node */
|
||||
private function customUrlChanges(array $node, object $item): bool
|
||||
{
|
||||
return (string) $item->type === 'custom' && $this->urlChanges($node, $item);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $args
|
||||
* @throws RuntimeException
|
||||
*/
|
||||
private function save(int $menuId, int $itemId, array $args): int
|
||||
{
|
||||
$result = wp_update_nav_menu_item($menuId, $itemId, $args);
|
||||
if (is_wp_error($result) || (int) $result <= 0) {
|
||||
$message = is_wp_error($result) ? $result->get_error_message() : 'no item ID returned';
|
||||
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- never rendered as HTML
|
||||
throw new RuntimeException(sprintf('Menu item %d could not be saved: %s', $itemId, $message));
|
||||
}
|
||||
|
||||
return (int) $result;
|
||||
}
|
||||
|
||||
/** @throws RuntimeException */
|
||||
private function remove(int $itemId): void
|
||||
{
|
||||
// Menu items have no trash in WordPress; the core menu editor deletes them the same way.
|
||||
$deleted = wp_delete_post($itemId, true);
|
||||
if (! $deleted instanceof WP_Post) {
|
||||
// phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- never rendered as HTML
|
||||
throw new RuntimeException(sprintf('Menu item %d could not be deleted.', $itemId));
|
||||
}
|
||||
|
||||
$this->deleted[] = $itemId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Undoes the running apply() and throws. Created items are deleted, touched items get
|
||||
* their previous data, parent and position back. Deleted items cannot come back with
|
||||
* their IDs – then (or when a restore step fails) the write is partial.
|
||||
*
|
||||
* @param array<int, object> $current
|
||||
* @throws WriteFailed Always.
|
||||
*/
|
||||
private function fail(int $menuId, array $current, Throwable $cause): never
|
||||
{
|
||||
$problems = [];
|
||||
foreach ($this->created as $itemId) {
|
||||
if (! wp_delete_post($itemId, true) instanceof WP_Post) {
|
||||
$problems[] = sprintf('created item %d not deleted', $itemId);
|
||||
}
|
||||
}
|
||||
|
||||
$order = array_flip(array_keys($current));
|
||||
foreach ($this->touched as $itemId) {
|
||||
$item = $current[$itemId];
|
||||
$args = $this->argsFromItem($item);
|
||||
$args['menu-item-parent-id'] = (int) $item->menu_item_parent;
|
||||
$args['menu-item-position'] = isset($item->menu_order) && (int) $item->menu_order > 0
|
||||
? (int) $item->menu_order
|
||||
: $order[$itemId] + 1;
|
||||
$args['menu-item-status'] = 'publish';
|
||||
try {
|
||||
$this->save($menuId, $itemId, $args);
|
||||
} catch (Throwable $e) {
|
||||
$problems[] = $e->getMessage();
|
||||
}
|
||||
}
|
||||
|
||||
$rolledBack = $problems === [] && $this->deleted === [];
|
||||
$detail = $cause->getMessage()
|
||||
. ($this->deleted !== [] ? '; already deleted: ' . implode(', ', $this->deleted) : '')
|
||||
. ($problems !== [] ? '; rollback: ' . implode('; ', $problems) : '');
|
||||
|
||||
throw new WriteFailed(
|
||||
'Das Menü konnte nicht gespeichert werden.',
|
||||
$rolledBack,
|
||||
null,
|
||||
null,
|
||||
$cause,
|
||||
$detail,
|
||||
sprintf('Menü %d ist möglicherweise teilweise geändert worden.', $menuId),
|
||||
'Den Aufruf nicht einfach wiederholen. Zuerst den aktuellen Stand mit lit-menu-get prüfen und ihn ggf. '
|
||||
. 'mit lit-menu-set-items anhand von previous_items (Stand vorher) wiederherstellen; entfernte '
|
||||
. 'Einträge müssen dabei neu angelegt werden. Dem Nutzer Bescheid geben.',
|
||||
['menu_id' => $menuId, 'previous_items' => MenuTree::build(array_values($current))]
|
||||
);
|
||||
}
|
||||
|
||||
/** @return array<string, mixed> The item's stored data, so a rewrite keeps everything. */
|
||||
private function argsFromItem(object $item): array
|
||||
{
|
||||
$isCustom = (string) $item->type === 'custom';
|
||||
|
||||
return [
|
||||
'menu-item-object-id' => (int) $item->object_id,
|
||||
'menu-item-object' => (string) $item->object,
|
||||
'menu-item-type' => (string) $item->type,
|
||||
'menu-item-title' => (string) $item->post_title,
|
||||
'menu-item-url' => $isCustom ? (string) $item->url : '',
|
||||
'menu-item-description' => (string) $item->description,
|
||||
'menu-item-attr-title' => (string) $item->attr_title,
|
||||
'menu-item-target' => (string) $item->target,
|
||||
'menu-item-classes' => implode(' ', array_filter((array) $item->classes)),
|
||||
'menu-item-xfn' => (string) $item->xfn,
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $node Validated new node.
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
private function argsFromNode(array $node): array
|
||||
{
|
||||
$objectId = (int) ($node['object_id'] ?? 0);
|
||||
|
||||
return match ($node['type']) {
|
||||
'post' => [
|
||||
'menu-item-type' => 'post_type',
|
||||
'menu-item-object' => (string) get_post_type($objectId),
|
||||
'menu-item-object-id' => $objectId,
|
||||
],
|
||||
'taxonomy' => [
|
||||
'menu-item-type' => 'taxonomy',
|
||||
'menu-item-object' => (string) get_term($objectId)->taxonomy,
|
||||
'menu-item-object-id' => $objectId,
|
||||
],
|
||||
default => ['menu-item-type' => 'custom', 'menu-item-object' => 'custom', 'menu-item-url' => ''],
|
||||
};
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user