Code Quality: Add PHPStan types for wp_insert_term(), wp_update_term(), and wp_delete_term()

[westonruter]

✅ Committed in r62682 (0527680)

---

Adds PHPStan array shapes and narrowed parameter/return types to wp_insert_term(), wp_update_term(), and wp_delete_term() in src/wp-includes/taxonomy.php. This removes the missingType.iterableValue errors reported for each function's $args parameter and return type at PHPStan level 10.

The types describe the contract these functions are intended to be called with, rather than what unguarded callers happen to pass today. Notably:

• parent is typed non-negative-int. sanitize_term_field() puts parent in $int_fields and silently clamps a negative value to 0, reparenting the term to the root. A numeric-string alternative would be redundant: for wp_insert_term() a query string matches the string branch of the union, so the array shape only ever constrains callers passing an actual array, where an int is what should be supplied; and wp_update_term() has no string branch at all.
• wp_delete_term()'s default is typed positive-int, since 0 is discarded by the subsequent term_exists() check.
• The $args shapes for wp_insert_term() and wp_update_term() are unsealed (...), because $args is forwarded to the pre_insert_term, wp_insert_term_data, wp_insert_term_duplicate_term_check, create_term, wp_update_term_data, and edit_term hooks, where plugins legitimately read arbitrary keys. wp_delete_term()'s shape is sealed, as its $args is consumed locally and never passed to a hook.
• description is string|null for wp_insert_term() but string for wp_update_term(). This asymmetry is deliberate: wp_insert_term() explicitly coerces a null description (// Coerce null description to strings, to avoid database errors.), while wp_update_term() has no such coercion.
• wp_delete_term()'s return is narrowed to bool|WP_Error|0, verified against all six return paths. This relies on the term_exists() conditional return type added in r62680.

These annotations surface new argument.type errors at several core call sites that pass $_POST or otherwise unvalidated data directly into these functions (wp-admin/edit-tags.php, wp-admin/includes/ajax-actions.php, wp-includes/nav-menu.php, class-wp-rest-terms-controller.php, class-wp-xmlrpc-server.php). These are pre-existing latent issues that the types now make visible, and are left to be addressed separately.

The two term_id: mixed return errors that remain inside wp_insert_term() and wp_update_term() stem from apply_filters() being typed as returning mixed, and are addressed in a separate pull request. See #12022.

Trac ticket: https://core.trac.wordpress.org/ticket/64898

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Reviewing the annotations against the function bodies and every core call site by diffing PHPStan level 10 output before and after; identifying that wp_update_term() cannot accept a query string, the null description/slug values, the unsealed-shape requirement, and the redundant numeric-string alternatives; and authoring the final non-negative-int/positive-int narrowings. All changes were reviewed, tested, and are owned by me.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.