$allowed Allowed members, for the enum and keys types only. * @return string|null The rendered value, or null when it fails its check. */ function aafm_activity_detail_field( string $type, $value, array $allowed = array() ): ?string { // The keys type is the only one whose candidate is a structured value, and it is answered // before the guard below because that guard rejects every array outright - which is the right // answer for all five scalar types and the wrong one for this. It reads KEY NAMES only, never // a value from the array, and every name must be a member of $allowed. See // aafm_activity_detail_key_list(). if ( 'keys' === $type ) { return aafm_activity_detail_key_list( $value, $allowed ); } if ( is_array( $value ) || is_object( $value ) || null === $value || is_bool( $value ) ) { return null; } // is_numeric() only accepts a numeric string with trailing whitespace since PHP 8.0, so an // identical value can validate on 8.x and fail on the plugin's PHP 7.4 floor. Trim a string // candidate before the check so both cases agree; a non-string $value passes through untouched. // The charlist adds \f: trim()'s default charlist (" \t\n\r\0\x0B") strips a vertical tab but // not a form feed, while is_numeric()'s own whitespace set includes both, so a trailing \f // would still diverge between 7.4 and 8.x without it. Only $candidate feeds the id/count // branches below; key/slug/enum read the untrimmed $value, so this never loosens those. $candidate = is_string( $value ) ? trim( $value, " \t\n\r\0\x0B\f" ) : $value; switch ( $type ) { case 'id': $id = is_numeric( $candidate ) ? (int) $candidate : 0; return $id > 0 ? (string) $id : null; case 'count': $count = is_numeric( $candidate ) ? (int) $candidate : -1; return $count >= 0 ? (string) $count : null; case 'key': $key = (string) $value; return preg_match( '/^[A-Za-z0-9_\-]{1,64}\z/', $key ) ? $key : null; case 'role': // A role as aafm/update-user stores it: sanitize_key() of the caller's value, so "Editor" logs // "editor". The result is always within the `key` character class. $role = sanitize_key( (string) $value ); return preg_match( '/^[a-z0-9_\-]{1,64}\z/', $role ) ? $role : null; case 'slug': $slug = (string) $value; return preg_match( '#^[a-z0-9\-]+/[a-z0-9\-]+\z#', $slug ) ? $slug : null; case 'template': // A block template's theme//slug identifier. Same character class as `key`, with the // double slash core uses between the theme and the template slug. $template = (string) $value; return preg_match( '#^[A-Za-z0-9_.\-]{1,64}//[A-Za-z0-9_.\-]{1,64}\z#', $template ) ? $template : null; case 'enum': $member = (string) $value; return in_array( $member, array_map( 'strval', $allowed ), true ) ? $member : null; } return null; } /** * Render the recognised KEY NAMES of a structured argument, or reject it. * * The one field type that reads a nested value, added for aafm/update-site-settings, whose whole * payload is a `settings` object: without this the row recorded that someone changed site settings * and could not say which, because arg_keys sees only the wrapper name `settings`. * * It does not weaken this file's central promise, and the reason is membership rather than * character filtering. A name is rendered only if it is in $allowed, which for the one entry using * this type resolves to aafm_allowed_site_settings() - the ability's OWN allowlist, chosen by the * site and never by the caller. So the column can only ever hold one of the setting names that * site permits. A caller who invents keys contributes nothing here, which is the property that * makes this different from the free-form string type the header tells a reviewer to refuse: there * is no input an agent can craft that lands its own text in this column. * * VALUES are deliberately never read, not even the two integer settings. Recording that * blogname changed is the audit fact; recording what it changed to would put caller-supplied prose * in the column, and blogname and blogdescription are free text that heads every RSS and Atom * feed. Splitting the difference - values for the numeric settings, names for the rest - would * make the column's guarantee depend on which setting was touched, and a guarantee with an * exception in it is the kind this codebase has been bitten by before. * * The charset check is belt and braces on top of membership: aafm_allowed_site_settings() is * filterable, so a site could add a name with punctuation in it, and this column has one job. * Sorted so the same call always renders the same string regardless of the caller's key order, and * capped with a trailing '~' on the same reasoning as the class-name cap below: a reader must be * able to tell a complete list from one that was cut. * * @param mixed $value The candidate value, expected to be an array. * @param array $allowed The setting names that may be rendered. * @return string|null The sorted, comma-separated names, or null when nothing recognisable is present. */ function aafm_activity_detail_key_list( $value, array $allowed ): ?string { if ( ! is_array( $value ) || array() === $value || array() === $allowed ) { return null; } $members = array_map( 'strval', $allowed ); $names = array(); foreach ( array_keys( $value ) as $name ) { // A list rather than a settings object yields integer keys; neither those nor an // unrecognised name contributes anything. if ( ! is_string( $name ) || ! in_array( $name, $members, true ) ) { continue; } if ( ! preg_match( '/^[A-Za-z0-9_\-]{1,64}\z/', $name ) ) { continue; } $names[] = $name; } if ( array() === $names ) { return null; } $names = array_values( array_unique( $names ) ); sort( $names ); $joined = implode( ', ', $names ); return mb_strlen( $joined ) > 128 ? mb_substr( $joined, 0, 128 ) . '~' : $joined; } /** * The complete, auditable allowlist of identifier-safe fields that may reach the detail column. * * Default deny: an ability absent from this map logs no detail at all, and an ability present here * logs only the fields it names. Central by design rather than a per-ability registry key like * args_builder: the security property is that a reviewer can read every field that can ever reach * an audit row in one place, and spreading it across twenty ability files destroys that. * * An arg may be marked `optional`; when it is absent or fails its check, the entry's * `fallback_template` (which takes the other args only) is used instead of `template`. * * @return array, optional?: bool}>, result_id?: string, result_type?: string, link?: string}> */ function aafm_activity_detail_map(): array { return array( 'aafm/update-post-meta' => array( /* translators: 1: meta key name. 2: the post's numeric ID. */ 'template' => __( 'Updated meta key `%1$s` on post #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/get-playbook' => array( /* translators: %s: the playbook slug. */ 'template' => __( 'Read playbook slug:%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'slug', 'type' => 'key', ), ), ), 'aafm/get-post-meta' => array( /* translators: 1: meta key name. 2: the post's numeric ID. */ 'template' => __( 'Read meta key `%1$s` on post #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/get-term-meta' => array( /* translators: 1: meta key name. 2: the term's numeric ID. */ 'template' => __( 'Read meta key `%1$s` on term #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'term_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/get-user-meta' => array( /* translators: 1: meta key name. 2: the user's numeric ID. */ 'template' => __( 'Read meta key `%1$s` on user #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'key', 'type' => 'key', ), array( 'key' => 'user_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/create-page' => array( /* translators: %s: the new page's numeric ID. */ 'template' => __( 'Created page #%s', 'agent-abilities-for-mcp' ), // Dotted path, NOT a bare 'id'. aafm_insert_post() returns // array( 'post' => aafm_redact_post( $created ) ), so the id lives at post.id, never at // the top level. Every create ability in this map wraps its payload the same way; a // bare key silently resolves to null and the row logs no detail. 'result_id' => 'post.id', 'link' => 'post', ), 'aafm/wc-update-order-status' => array( /* translators: 1: the order's numeric ID. 2: the new order status key. */ 'template' => __( 'Set order #%1$s to status `%2$s`', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'order_id', 'type' => 'id', ), array( 'key' => 'status', 'type' => 'enum', 'enum' => 'aafm_activity_order_statuses', ), ), 'link' => 'order', ), // The starter set below extends the three entries above to fifteen abilities. Every key // name is verified against the ability's own args builder (or, for a result entry, the // executor's actual return shape) before being written here - see LESSONS-LEARNED and // DetailTest for why a guessed key is a silent-wrong-answer bug, not a loud one. 'aafm/create-post' => array( /* translators: %s: the new post's numeric ID. */ 'template' => __( 'Created post #%s', 'agent-abilities-for-mcp' ), // aafm_exec_create_post() delegates to aafm_insert_post(), which returns // array( 'post' => aafm_redact_post( … ) ) - same wrapped shape as create-page. 'result_id' => 'post.id', 'link' => 'post', ), 'aafm/create-draft' => array( /* translators: %s: the new draft's numeric ID. */ 'template' => __( 'Created draft #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'post.id', 'link' => 'post', ), 'aafm/create-user' => array( /* translators: %s: the new user's numeric ID. */ 'template' => __( 'Created user #%s', 'agent-abilities-for-mcp' ), // aafm_exec_create_user() returns array( 'user' => aafm_rich_user( … ) ), never a // top-level id. 'result_id' => 'user.id', 'link' => 'user', ), 'aafm/delete-post-meta' => array( /* translators: 1: meta key name. 2: the post's numeric ID. */ 'template' => __( 'Deleted meta key `%1$s` on post #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/update-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/update-page' => array( /* translators: %s: the page's numeric ID. */ 'template' => __( 'Updated page #%s', 'agent-abilities-for-mcp' ), // aafm_args_update_page() names its own id field page_id, not post_id - confirmed // against pages.php. update-post and update-page take different keys even though // both end up writing the same wp_posts row. 'args' => array( array( 'key' => 'page_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/delete-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Deleted post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/delete-page' => array( /* translators: %s: the page's numeric ID. */ 'template' => __( 'Deleted page #%s', 'agent-abilities-for-mcp' ), // page_id, not post_id - see aafm/update-page above. 'args' => array( array( 'key' => 'page_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/trash-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Trashed post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/trash-page' => array( /* translators: %s: the page's numeric ID. */ 'template' => __( 'Trashed page #%s', 'agent-abilities-for-mcp' ), // page_id, not post_id - see aafm/update-page above. 'args' => array( array( 'key' => 'page_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/restore-revision' => array( /* translators: %s: the restored revision's numeric ID. */ 'template' => __( 'Restored revision #%s', 'agent-abilities-for-mcp' ), // revision_id, confirmed against aafm_args_restore_revision(). post_id is also a // required arg on this ability but is deliberately not declared here - the map's job // is to name the one identifier worth showing, not to mirror the whole schema. 'args' => array( array( 'key' => 'revision_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/update-user' => array( /* translators: 1: the user's numeric ID. 2: the role slug assigned, such as shop_manager. */ 'template' => __( 'Updated user #%1$s, role set to %2$s', 'agent-abilities-for-mcp' ), /* translators: %s: the user's numeric ID. */ 'fallback_template' => __( 'Updated user #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'user_id', 'type' => 'id', ), // The role slug as the ability stores it (sanitize_key()). Optional: a call that changes no // role, or one whose role has no identifier characters, gets the fallback template. array( 'key' => 'role', 'type' => 'role', 'optional' => true, ), ), 'link' => 'user', ), 'aafm/delete-user' => array( /* translators: %s: the user's numeric ID. */ 'template' => __( 'Deleted user #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'user_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/wc-create-order-refund' => array( /* translators: %s: the order's numeric ID. */ 'template' => __( 'Refunded order #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'order_id', 'type' => 'id', ), ), 'link' => 'order', ), 'aafm/wc-update-payment-gateway' => array( /* translators: %s: the payment gateway's id slug. */ 'template' => __( 'Updated payment gateway `%s`', 'agent-abilities-for-mcp' ), // gateway_id is a slug ("bacs", "cod", "stripe"), never a numeric id, so it takes the // key type and declares no link - there is no post/user/term/order to point it at. 'args' => array( array( 'key' => 'gateway_id', 'type' => 'key', ), ), ), // The permanent-delete sweep. Every ability named by // aafm_permanent_delete_abilities() in helpers.php now records the identifier of what it // destroyed. Before this, nine of those thirteen logged detail:null, so the audit trail // could say that an agent permanently deleted something but never say WHAT - measured on // the wire, where aafm/delete-comment resolved to detail:null carrying only the key NAME // "comment_id", one second after aafm/delete-post resolved to "Deleted post #355935". // That asymmetry shipped in 1.6.3 and earlier. // // The completeness of this block is not maintained by hand. DetailTest's // test_every_permanent_delete_ability_records_an_identifier derives the destructive set // from aafm_permanent_delete_abilities() at runtime and fails the moment a fourteenth // permanent delete is added without an entry here, which is the guard whose absence let // the original nine ship. // // Every key below is read from that ability's OWN args builder, never inferred from a // sibling. aafm/delete-user-meta is why that rule is written down: it names its parameter // `key` where the post-meta abilities name theirs `meta_key`, and its schema description // says in as many words that the two "are not interchangeable". A sibling-shaped guess of // `meta_key` there resolves to null through the all-or-nothing rule in // aafm_build_activity_detail(), logging exactly the blindness this block removes, with // every gate still green. // // All nine read the caller's arguments rather than a result_id, and that is forced rather // than stylistic: register.php builds the args detail on the opening 'started' row before // the execute callback runs, which is the only moment the object still exists. A permanent // delete has no identifier left to dig out of its return value. 'aafm/delete-comment' => array( /* translators: %s: the comment's numeric ID. */ 'template' => __( 'Deleted comment #%s', 'agent-abilities-for-mcp' ), // comment_id, confirmed against aafm_args_delete_comment() in comments.php. No link: // aafm_activity_detail_link() resolves post, user, term and order, and there is no // comment type. Adding one is a change to that renderer, not to this map. 'args' => array( array( 'key' => 'comment_id', 'type' => 'id', ), ), ), 'aafm/delete-media' => array( /* translators: %s: the attachment's numeric ID. */ 'template' => __( 'Deleted media #%s', 'agent-abilities-for-mcp' ), // attachment_id, not media_id or post_id - confirmed against aafm_args_delete_media(). 'args' => array( array( 'key' => 'attachment_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/delete-menu' => array( /* translators: %s: the navigation menu's numeric ID. */ 'template' => __( 'Deleted menu #%s', 'agent-abilities-for-mcp' ), // menu_id, confirmed against aafm_args_delete_menu(). A navigation menu is a nav_menu // TERM, so the link type is term rather than post. 'args' => array( array( 'key' => 'menu_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/delete-menu-item' => array( /* translators: %s: the menu item's numeric ID. */ 'template' => __( 'Deleted menu item #%s', 'agent-abilities-for-mcp' ), // item_id, NOT menu_item_id and not the menu_id its sibling above takes - confirmed // against aafm_args_delete_menu_item(). A menu item is a nav_menu_item post. 'args' => array( array( 'key' => 'item_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/delete-revision' => array( /* translators: %s: the deleted revision's numeric ID. */ 'template' => __( 'Deleted revision #%s', 'agent-abilities-for-mcp' ), // revision_id, confirmed against aafm_args_delete_revision(). post_id is also required // by that ability and is deliberately not declared, matching aafm/restore-revision // above: the map names the one identifier worth showing, and a second id field would // fail the one-linkable-id rule. 'args' => array( array( 'key' => 'revision_id', 'type' => 'id', ), ), 'link' => 'post', ), // The update counterparts of the two delete entries below. A meta write is exactly as // irreversible as a meta delete - there is no revision history for post, term or user meta, // so overwriting a value destroys the previous one for good - yet only the deletes recorded // what they touched. Before this, a successful write logged detail:null with arg_keys holding // only the parameter NAMES (`user_id,key,value`), so the row could say an agent had written // some user meta and name neither the user nor the key. // // Names and ids only, never the `value` these two carry and the deletes do not. Unlike // aafm/update-site-settings, which constrains rendering to its ability's own closed allowlist, // there is no closed set to check against here: the user-meta allowlist supports an allow-all // `*` wildcard, so the `key` type's charset is the containment, the same as the four meta // entries that shipped before this one. // // A hard-blocked key such as session_tokens is refused by the PERMISSION callback rather than // inside execute, so its NAME does land here on the denied path. That is deliberate and is the // row an operator most wants: an attempted privilege escalation, recorded with status 'denied' // and nothing written. DetailTest pins both halves. 'aafm/update-term-meta' => array( /* translators: 1: meta key name. 2: the term's numeric ID. */ 'template' => __( 'Updated meta key `%1$s` on term #%2$s', 'agent-abilities-for-mcp' ), // meta_key and term_id, confirmed against aafm_args_update_term_meta() in terms.php. The // optional taxonomy arg and the required `value` are both left out: one is not an // identifier of the thing written, the other is what this column must never hold. 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'term_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/update-user-meta' => array( /* translators: 1: meta key name. 2: the user's numeric ID. */ 'template' => __( 'Updated meta key `%1$s` on user #%2$s', 'agent-abilities-for-mcp' ), // `key`, NOT `meta_key` - confirmed against aafm_args_update_user_meta(). BOTH user-meta // abilities diverge from the post-meta family's spelling, so copying from the wrong // neighbour still silently yields null here. 'args' => array( array( 'key' => 'key', 'type' => 'key', ), array( 'key' => 'user_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/delete-term-meta' => array( /* translators: 1: meta key name. 2: the term's numeric ID. */ 'template' => __( 'Deleted meta key `%1$s` on term #%2$s', 'agent-abilities-for-mcp' ), // meta_key and term_id, confirmed against aafm_args_delete_term_meta(). The ability // also takes an optional taxonomy, which is not an identifier of the thing deleted and // is left out. The term itself survives, so unlike its neighbours here this link // resolves to a live edit screen. 'args' => array( array( 'key' => 'meta_key', 'type' => 'key', ), array( 'key' => 'term_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/delete-user-meta' => array( /* translators: 1: meta key name. 2: the user's numeric ID. */ 'template' => __( 'Deleted meta key `%1$s` on user #%2$s', 'agent-abilities-for-mcp' ), // `key`, NOT `meta_key` - see the block comment above. Confirmed against // aafm_args_delete_user_meta(), whose own description states the post-meta abilities // name the equivalent parameter differently and that the two are not interchangeable. 'args' => array( array( 'key' => 'key', 'type' => 'key', ), array( 'key' => 'user_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/wc-delete-product' => array( /* translators: %s: the product's numeric ID. */ 'template' => __( 'Deleted product #%s', 'agent-abilities-for-mcp' ), // product_id, confirmed against aafm_args_wc_delete_product(). A product is a post, so // the link type is post; 'order' is only for rows whose id is a WooCommerce order. 'args' => array( array( 'key' => 'product_id', 'type' => 'id', ), ), 'link' => 'post', ), // S-5, the same audit blindness away from the delete abilities. A successful // update-site-settings call recorded detail:null, so the log showed that an agent had // changed the site's settings and could not say which - arg_keys sees only the wrapper // name `settings`, never what is inside it. Reproduced before being fixed: a call setting // blogname and posts_per_page succeeded, both options really changed, and the row's detail // was null. // // Names only, never values, and the enum is the ability's own allowlist rather than a // literal list, so the two cannot drift and a site that filters the allowlist gets a // truthful row. No link: a setting is not a post, user, term or order. 'aafm/update-site-settings' => array( /* translators: %s: comma-separated list of the site setting names that were changed. */ 'template' => __( 'Updated site settings: %s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'settings', 'type' => 'keys', 'enum' => 'aafm_allowed_site_settings', ), ), ), 'aafm/wc-delete-product-variation' => array( /* translators: %s: the variation's numeric ID. */ 'template' => __( 'Deleted product variation #%s', 'agent-abilities-for-mcp' ), // variation_id, not product_id - confirmed against // aafm_args_wc_delete_product_variation(). A variation is its own product_variation // post, so the id here is not the parent's. 'args' => array( array( 'key' => 'variation_id', 'type' => 'id', ), ), 'link' => 'post', ), // Every remaining write ability. Each names the object it touched so an activity row can say // what changed. An update reads its target from the call's own arguments; a create reads the new // object's id from the return value. Keys were checked against each ability's args builder and // output schema by DetailTest. 'aafm/replace-in-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a text replace on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/replace-block' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Replaced a block in post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/replace-sitewide' => array( /* translators: %s: how many posts were changed. */ 'template' => __( 'Replaced text in %s posts', 'agent-abilities-for-mcp' ), 'result_id' => 'updated_posts', 'result_type' => 'count', ), 'aafm/create-cpt-item' => array( /* translators: %s: the new item's numeric ID. */ 'template' => __( 'Created content item #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'post.id', 'link' => 'post', ), 'aafm/update-cpt-item' => array( /* translators: %s: the item's numeric ID. */ 'template' => __( 'Updated content item #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/create-term' => array( /* translators: %s: the new term's numeric ID. */ 'template' => __( 'Created term #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'term.id', 'link' => 'term', ), 'aafm/update-term' => array( /* translators: %s: the term's numeric ID. */ 'template' => __( 'Updated term #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'term_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/add-post-terms' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Added terms to post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/moderate-comment' => array( /* translators: 1: the comment's numeric ID. 2: the moderation action. */ 'template' => __( 'Moderated comment #%1$s: %2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'comment_id', 'type' => 'id', ), array( 'key' => 'action', 'type' => 'enum', 'enum' => array( 'approve', 'unapprove', 'spam', 'trash' ), ), ), ), 'aafm/create-comment' => array( /* translators: %s: the new comment's numeric ID. */ 'template' => __( 'Created comment #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'comment.id', ), 'aafm/update-comment' => array( /* translators: %s: the comment's numeric ID. */ 'template' => __( 'Updated comment #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'comment_id', 'type' => 'id', ), ), ), 'aafm/set-featured-image' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Set the featured image on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/upload-media' => array( /* translators: %s: the new attachment's numeric ID. */ 'template' => __( 'Uploaded media #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'attachment_id', 'link' => 'post', ), 'aafm/upload-media-from-url' => array( /* translators: %s: the new attachment's numeric ID. */ 'template' => __( 'Uploaded media #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'attachment_id', 'link' => 'post', ), 'aafm/update-media' => array( /* translators: %s: the attachment's numeric ID. */ 'template' => __( 'Updated media #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'attachment_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/create-block' => array( /* translators: %s: the new block's numeric ID. */ 'template' => __( 'Created block #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'post', ), 'aafm/update-block' => array( /* translators: %s: the block's numeric ID. */ 'template' => __( 'Updated block #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'block_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/delete-block' => array( /* translators: %s: the block's numeric ID. */ 'template' => __( 'Deleted block #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'block_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/undo-change' => array( /* translators: %s: the numeric ID of the change that was undone. */ 'template' => __( 'Undid change #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'change_id', 'type' => 'id', ), ), ), 'aafm/create-menu' => array( /* translators: %s: the new menu's numeric ID. */ 'template' => __( 'Created menu #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'term', ), 'aafm/update-menu' => array( /* translators: %s: the menu's numeric ID. */ 'template' => __( 'Updated menu #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'menu_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/create-menu-item' => array( /* translators: %s: the new menu item's numeric ID. */ 'template' => __( 'Created menu item #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'post', ), 'aafm/update-menu-item' => array( /* translators: %s: the menu item's numeric ID. */ 'template' => __( 'Updated menu item #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'item_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/update-navigation' => array( /* translators: %s: the navigation's numeric ID. */ 'template' => __( 'Updated navigation #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/update-template' => array( /* translators: %s: the template's theme//slug identifier. */ 'template' => __( 'Updated template `%s`', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'template_id', 'type' => 'template', ), ), ), 'aafm/yoast-update-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated Yoast SEO fields on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/rankmath-update-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated Rank Math fields on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/rankmath-update-schema' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated Rank Math schema on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/aioseo-update-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated All in One SEO fields on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/slim-seo-update-post' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated Slim SEO fields on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/acf-update-post-fields' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Updated custom fields on post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/acf-update-term-fields' => array( /* translators: %s: the term's numeric ID. */ 'template' => __( 'Updated custom fields on term #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'term_id', 'type' => 'id', ), ), 'link' => 'term', ), 'aafm/acf-update-user-fields' => array( /* translators: %s: the user's numeric ID. */ 'template' => __( 'Updated custom fields on user #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'user_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/wc-create-product' => array( /* translators: %s: the new product's numeric ID. */ 'template' => __( 'Created product #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'post', ), 'aafm/wc-update-product' => array( /* translators: %s: the product's numeric ID. */ 'template' => __( 'Updated product #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'product_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wc-create-product-variation' => array( /* translators: %s: the new variation's numeric ID. */ 'template' => __( 'Created product variation #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'post', ), 'aafm/wc-update-product-variation' => array( /* translators: %s: the variation's numeric ID. */ 'template' => __( 'Updated product variation #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'variation_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wc-create-product-attribute' => array( /* translators: %s: the new attribute's numeric ID. */ 'template' => __( 'Created product attribute #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', ), 'aafm/wc-update-product-attribute' => array( /* translators: %s: the attribute's numeric ID. */ 'template' => __( 'Updated product attribute #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'attribute_id', 'type' => 'id', ), ), ), 'aafm/wc-create-order' => array( /* translators: %s: the new order's numeric ID. */ 'template' => __( 'Created order #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'order', ), 'aafm/wc-update-order' => array( /* translators: %s: the order's numeric ID. */ 'template' => __( 'Updated order #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'order_id', 'type' => 'id', ), ), 'link' => 'order', ), 'aafm/wc-create-order-note' => array( /* translators: %s: the order's numeric ID. */ 'template' => __( 'Added a note to order #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'order_id', 'type' => 'id', ), ), 'link' => 'order', ), 'aafm/wc-create-customer' => array( /* translators: %s: the new customer's numeric ID. */ 'template' => __( 'Created customer #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'user', ), 'aafm/wc-update-customer' => array( /* translators: %s: the customer's numeric ID. */ 'template' => __( 'Updated customer #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'customer_id', 'type' => 'id', ), ), 'link' => 'user', ), 'aafm/wc-create-coupon' => array( /* translators: %s: the new coupon's numeric ID. */ 'template' => __( 'Created coupon #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', 'link' => 'post', ), 'aafm/wc-update-coupon' => array( /* translators: %s: the coupon's numeric ID. */ 'template' => __( 'Updated coupon #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'coupon_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wc-create-shipping-zone' => array( /* translators: %s: the new shipping zone's numeric ID. */ 'template' => __( 'Created shipping zone #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', ), 'aafm/wc-update-shipping-zone' => array( /* translators: %s: the shipping zone's numeric ID. */ 'template' => __( 'Updated shipping zone #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'zone_id', 'type' => 'id', ), ), ), 'aafm/wc-create-shipping-method' => array( /* translators: %s: the new shipping method instance's numeric ID. */ 'template' => __( 'Created shipping method #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'instance_id', ), 'aafm/wc-update-shipping-method' => array( /* translators: %s: the shipping method instance's numeric ID. */ 'template' => __( 'Updated shipping method #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'instance_id', 'type' => 'id', ), ), ), 'aafm/wc-create-tax-rate' => array( /* translators: %s: the new tax rate's numeric ID. */ 'template' => __( 'Created tax rate #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'id', ), 'aafm/wc-update-tax-rate' => array( /* translators: %s: the tax rate's numeric ID. */ 'template' => __( 'Updated tax rate #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'rate_id', 'type' => 'id', ), ), ), 'aafm/wc-create-tax-class' => array( /* translators: %s: the new tax class's slug. */ 'template' => __( 'Created tax class `%s`', 'agent-abilities-for-mcp' ), 'result_id' => 'slug', 'result_type' => 'key', ), 'aafm/tec-create-event' => array( /* translators: %s: the new event's numeric ID. */ 'template' => __( 'Created event #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'event.id', 'link' => 'post', ), 'aafm/tec-update-event' => array( /* translators: %s: the event's numeric ID. */ 'template' => __( 'Updated event #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'event_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/tec-delete-event' => array( /* translators: %s: the event's numeric ID. */ 'template' => __( 'Trashed event #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'event_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/tec-create-venue' => array( /* translators: %s: the new venue's numeric ID. */ 'template' => __( 'Created venue #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'venue.id', 'link' => 'post', ), 'aafm/tec-update-venue' => array( /* translators: %s: the venue's numeric ID. */ 'template' => __( 'Updated venue #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'venue_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/tec-create-organizer' => array( /* translators: %s: the new organizer's numeric ID. */ 'template' => __( 'Created organizer #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'organizer.id', 'link' => 'post', ), 'aafm/tec-update-organizer' => array( /* translators: %s: the organizer's numeric ID. */ 'template' => __( 'Updated organizer #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'organizer_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-replace-text' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a text replace on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-update-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element update on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-insert-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element insert on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-move-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element move on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-remove-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element removal on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-insert-library-item' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a library item insert on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-update-page-css' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a page CSS update on Avada page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-update-page-options' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a page options update on Avada post #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-replace-text' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a text replace on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-update-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element update on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-insert-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element insert on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-move-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element move on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-remove-element' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran an element removal on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-insert-template' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a template insert on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/avada-update-global-options' => array( /* translators: %s: comma-separated list of the Avada Global Option keys in the call. */ 'template' => __( 'Ran an Avada Global Options update: %s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'set', 'type' => 'keys', 'enum' => 'aafm_avada_global_option_keys', ), ), ), 'aafm/avada-update-layout' => array( /* translators: %s: the layout's numeric ID. */ 'template' => __( 'Ran an Avada layout update on layout #%s', 'agent-abilities-for-mcp' ), 'fallback_template' => __( 'Ran an Avada layout update on the Global Layout', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'layout_id', 'type' => 'id', 'optional' => true, ), ), ), 'aafm/avada-import-studio-item' => array( /* translators: 1: the Avada Studio item type, 2: the Studio item's numeric ID. */ 'template' => __( 'Ran an Avada Studio import of %1$s item #%2$s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'type', 'type' => 'enum', 'enum' => 'aafm_avada_studio_types', ), array( 'key' => 'item_id', 'type' => 'id', ), ), ), 'aafm/avada-update-slider-settings' => array( /* translators: %s: the slider's numeric term ID. */ 'template' => __( 'Ran an Avada slider settings update on slider #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'term_id', 'type' => 'id', ), ), ), 'aafm/wpbakery-update-page-code' => array( /* translators: %s: the post's numeric ID. */ 'template' => __( 'Ran a page code update on WPBakery page #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'post_id', 'type' => 'id', ), ), 'link' => 'post', ), 'aafm/wpbakery-update-settings' => array( /* translators: %s: comma-separated list of the WPBakery setting keys in the call. */ 'template' => __( 'Ran a WPBakery settings update: %s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'set', 'type' => 'keys', 'enum' => 'aafm_wpbakery_settings_keys', ), ), ), 'aafm/geodirectory-create-listing' => array( /* translators: %s: the new listing's numeric ID. */ 'template' => __( 'Created listing #%s', 'agent-abilities-for-mcp' ), 'result_id' => 'listing_id', 'link' => 'post', ), 'aafm/geodirectory-update-listing' => array( /* translators: %s: the listing's numeric ID. */ 'template' => __( 'Updated listing #%s', 'agent-abilities-for-mcp' ), 'args' => array( array( 'key' => 'listing_id', 'type' => 'id', ), ), 'link' => 'post', ), ); } /** * Resolve an enum declaration to its allowed members. * * A declaration may be a literal list or the name of a callable returning one, so a set that is * only knowable at runtime (WooCommerce's order statuses) does not have to be duplicated here. * An unresolvable declaration yields an empty set, which rejects every value: fail closed. * * @param mixed $declared Literal list, or the name of a callable returning one. * @return array */ function aafm_activity_detail_enum( $declared ): array { if ( is_array( $declared ) ) { return array_values( array_map( 'strval', $declared ) ); } if ( is_string( $declared ) && function_exists( $declared ) ) { $members = call_user_func( $declared ); return is_array( $members ) ? array_values( array_map( 'strval', $members ) ) : array(); } return array(); } /** * The order-status keys WooCommerce itself defines, or an empty set when WooCommerce is absent. * * Reads wc_get_order_statuses() rather than hardcoding, so a site with a custom status registered * through WooCommerce's own API logs it correctly and a typo still fails the enum check. * * @return array */ function aafm_activity_order_statuses(): array { if ( ! function_exists( 'wc_get_order_statuses' ) ) { return array(); } return array_map( static fn( string $key ): string => (string) preg_replace( '/^wc-/', '', $key ), array_keys( wc_get_order_statuses() ) ); } /** * Build a row's detail from an ability's own arguments, or return null. * * Null is the normal outcome: most abilities declare nothing, and one that declares a field the * caller did not send (or sent in a shape that fails its type check) logs no detail rather than a * half-built string. Detail is observability, never control flow. * * A row that records a refused or failed call gets the same text behind "Attempted:", so a denied * write does not read as one that happened. The wrap lives here, once, for every mapped template. * * @param string $ability Ability name. * @param array $args The call's own arguments. * @param string $status The row's status. 'denied' and 'error' mark the text as an attempt. * @return string|null */ function aafm_build_activity_detail( string $ability, array $args, string $status = 'started' ): ?string { $entry = aafm_activity_detail_map()[ $ability ] ?? null; if ( null === $entry || empty( $entry['args'] ) ) { return null; } $values = array(); $template = (string) $entry['template']; foreach ( $entry['args'] as $field ) { $allowed = isset( $field['enum'] ) ? aafm_activity_detail_enum( $field['enum'] ) : array(); $rendered = aafm_activity_detail_field( (string) $field['type'], $args[ $field['key'] ] ?? null, $allowed ); if ( null === $rendered && ! empty( $field['optional'] ) && isset( $entry['fallback_template'] ) ) { // ponytail: one optional field per entry, swapped for the fallback template. A second one // would need a template per combination. $template = (string) $entry['fallback_template']; continue; } if ( null === $rendered ) { return null; // All or nothing: never emit a template with a hole in it. } $values[] = $rendered; } $detail = vsprintf( $template, $values ); if ( in_array( $status, array( 'denied', 'error' ), true ) ) { /* translators: %s: what the call tried to do, such as "Updated meta key `x` on post #5". */ return sprintf( __( 'Attempted: %s', 'agent-abilities-for-mcp' ), $detail ); } return $detail; } /** * Build a row's detail from an ability's RETURN value, for creates whose identifier does not * exist until after execution. Only a single positive integer is ever read. * * The result_id is a dot-separated path, because no create ability in this plugin returns its id at * the top level: the post writers return array( 'post' => aafm_redact_post( … ) ) and the user * writer returns array( 'user' => aafm_rich_user( … ) ). A bare key would resolve to null on * every one of them and the feature would silently log nothing. * * @param string $ability Ability name. * @param mixed $result The execute callback's return value. * @return string|null */ function aafm_build_activity_detail_from_result( string $ability, $result ): ?string { // A failed call records WHY it failed, for every ability rather than only the mapped ones. The error CODE and never get_error_message(): a code is an identifier by construction, // while a message is free-form prose that routinely interpolates the value that failed (see // aafm_wc_invalid_coupon_amount, which quotes the rejected amount). This branch sits before the // is_array() return below, which a WP_Error would otherwise fall straight through. // // A bridged ability's code is recorded too, but behind a prefix. "A code is an identifier by // construction" holds for the codes this plugin ships (every `new WP_Error(` under includes/ takes // a string literal) and, by trust, for an ability a site adds through aafm_abilities_registry. It // does not hold for a foreign plugin's, which can build a code out of its input: // `new WP_Error( 'duplicate_sku_' . $sku )` passes the key check below and puts a fragment of the // argument in this column. So a code a foreign plugin returned is recorded as // AAFM_BRIDGE_FOREIGN_CODE_PREFIX plus the key-checked code, which also keeps it from reading as one // of ours. Only an error made here by aafm_bridge_own_error() is recorded plain. The message and the // error data are never read. A bridged crash still records its exception class and throw site, // which the engine supplies. if ( is_wp_error( $result ) ) { $code = aafm_activity_detail_field( 'key', $result->get_error_code() ); if ( null === $code || '' === $code ) { return null; } if ( str_starts_with( $ability, AAFM_BRIDGE_NAMESPACE . '/' ) && ! aafm_bridge_is_own_error( $result ) ) { return AAFM_BRIDGE_FOREIGN_CODE_PREFIX . $code; } return $code; } $entry = aafm_activity_detail_map()[ $ability ] ?? null; if ( null === $entry || empty( $entry['result_id'] ) || ! is_array( $result ) ) { return null; } // result_type is `id` unless the entry says otherwise: a count (replace-sitewide) or a key // (a tax class has a slug, not a number). Every type is one of the identifier-safe checks above. $type = isset( $entry['result_type'] ) ? (string) $entry['result_type'] : 'id'; $id = aafm_activity_detail_field( $type, aafm_activity_detail_dig( $result, (string) $entry['result_id'] ) ); return ( null === $id ) ? null : sprintf( (string) $entry['template'], $id ); } /** * Build a row's detail from a caught throwable: its class and where it was thrown, never its * message. * * Deliberately NOT a new aafm_activity_detail_field() type: the parts here come from the PHP * engine, not from caller input, so they need constraining rather than validating, and adding a * free-form string type is the change this file's header tells a reviewer to refuse. * * $e->getMessage() is never read. A vendor exception message routinely interpolates the value that * caused it - a rejected email address, a duplicated SKU, a download filename - and the log's * central promise, stated in the wp.org listing and not only in this codebase, is that free-text * argument content is never stored. The class and the throw site identify the defect more precisely than the * prose does anyway. * * get_class() needs the guard below, not only the message: PHP renders an anonymous class as * "Parent@anonymous\0:$", so the raw class name of an anonymous * throwable carries the site's install path AND a NUL byte, and aafm_sanitize_activity_detail() * removes neither (a NUL is valid UTF-8, so wp_check_invalid_utf8() passes it through). Cutting at * the NUL leaves "Parent@anonymous", which is all the useful part. PHP 7.4 writes "class" where * 8.0+ writes the parent's name, so on the floor the parent is derived instead - see below - and * a row records the same shape on every supported version. * * A class name that arrived here longer or wider than the row can hold gets a trailing '~', so a * reader can tell a recorded name from a recorded name that is only close. That covers characters * the filter removed, a name cut at the 128-character cap, and a name the filter emptied entirely. * * @param \Throwable $e The caught exception or error. * @return string A bounded, value-free detail, e.g. "WC_Data_Exception at abstract-wc-data.php:1001". */ function aafm_build_activity_detail_from_exception( \Throwable $e ): string { $class = get_class( $e ); $nul = strpos( $class, "\0" ); if ( false !== $nul ) { $class = substr( $class, 0, $nul ); } // PHP 8.0 renders an anonymous class as "Parent@anonymous...", but 7.4 - this plugin's floor - // renders it as the literal "class@anonymous...", so the cut above leaves a name that // identifies nothing. get_parent_class() returns the same parent on both versions, so deriving // it here makes a 7.4 site's row name the thrown class as precisely as an 8.x site's, rather // than leaving the floor with a quietly less useful audit log than the docblock promises. // // Keyed on the string the engine actually produced, not on PHP_VERSION_ID: it fires exactly // when the name is uninformative and is a no-op the moment the engine supplies a parent itself. // A parent that is itself anonymous carries its own NUL, so it gets the same cut. The // is_string() guard is belt and braces - PHP rejects a userland class that implements Throwable // without extending Exception or Error, so an anonymous throwable always has a parent, and // get_parent_class() returns false only when there is none. if ( 'class@anonymous' === $class ) { $parent = get_parent_class( $e ); if ( is_string( $parent ) ) { $parent_nul = strpos( $parent, "\0" ); $class = ( false === $parent_nul ? $parent : substr( $parent, 0, $parent_nul ) ) . '@anonymous'; } } // A PHP class name is [A-Za-z0-9_\] plus the '@anonymous' marker kept above; anything else is // not a class name and has no business in an audit row. // // PHP does allow bytes \x80-\xff in a class name, though, so the filter can turn a real class // into a DIFFERENT real one: `Exceptiéon` records as `Exception`, which reads as an ordinary // name and points a forensic reader at the wrong class entirely. A trailing '~' says the name // that reached this row is not the name that was thrown. The filter is not widened to \p{L}\p{N} // instead, because /u makes preg_replace() return null on invalid UTF-8 and this is the one // place that cannot afford to. // // One marker for every way the name can be cut, compared against what came in rather than // against the filter alone. The cap cuts too: a 150-character class truncates to exactly 128, // and an unmarked 128 characters can be a real class whose whole name is those 128 characters, // which is the collision the marker exists to prevent. A name the filter empties falls back to // the Throwable sentinel and is marked as well, so total loss never reads quieter than partial // loss. The anonymous-class path is untouched: the NUL cut above has already reduced it to // "Parent@anonymous", which the filter and the cap both leave alone. $raw = $class; $filtered = (string) preg_replace( '/[^A-Za-z0-9_\\\\@]/', '', $class ); $class = '' === $filtered ? 'Throwable' : mb_substr( $filtered, 0, 128 ); if ( $class !== $raw ) { $class .= '~'; } // basename() drops the install path; the character filter absorbs the " : evaluated code" // suffix PHP appends to getFile() when the throw happens inside a runtime-evaluated string. $file = (string) preg_replace( '/[^A-Za-z0-9._\-]/', '', basename( $e->getFile() ) ); $file = '' === $file ? 'unknown' : mb_substr( $file, 0, 64 ); return sprintf( '%1$s at %2$s:%3$d', $class, $file, max( 0, $e->getLine() ) ); } /** * Walk a dot-separated path into a nested array, or return null. * * Deliberately tiny and total: any missing segment, or a non-array encountered mid-path, yields * null rather than a warning. Callers treat null as "no detail", which is always a safe outcome. * * @param array $data Source array. * @param string $path Dot-separated path, e.g. 'post.id'. * @return mixed */ function aafm_activity_detail_dig( array $data, string $path ) { $cursor = $data; foreach ( explode( '.', $path ) as $segment ) { if ( ! is_array( $cursor ) || ! array_key_exists( $segment, $cursor ) ) { return null; } $cursor = $cursor[ $segment ]; } return $cursor; } /** * The object type an ability's detail identifier refers to, for render-time linking. * * @param string $ability Ability name. * @return string|null One of post|user|term|order, or null when the ability declares no link. */ function aafm_activity_detail_link_type( string $ability ): ?string { $link = aafm_activity_detail_map()[ $ability ]['link'] ?? null; return in_array( $link, array( 'post', 'user', 'term', 'order' ), true ) ? $link : null; }