WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#22801 closed defect (bug) (fixed)

Update documentation on wp_insert_term to state that it will return an error if inserting an existing term.

Reported by: lgedeon Owned by: SergeyBiryukov
Milestone: 3.7 Priority: normal
Severity: normal Version: 2.3
Component: Inline Docs Keywords: has-patch
Focuses: Cc:
PR Number:

Description

phpdoc for wp_insert_term() states:

If both the term id and taxonomy exist previously, then an array will be returned that contains the term id and the contents of what is returned.

However it returns an error object instead. That may have changed with #13481. Anyway, returning an error seems to be an acceptable solution. Although, #16567 might change that a bit.

Should we just adjust the docs to fit the current behavior?

Attachments (4)

22801.diff (4.8 KB) - added by DrewAPicture 6 years ago.
docblock redo
22801.2.diff (4.8 KB) - added by DrewAPicture 6 years ago.
tense, wrapping
22801.3.diff (4.8 KB) - added by lgedeon 6 years ago.
Alternate list of of error triggers, and tense fix typo fix
22801.4.diff (1.5 KB) - added by SergeyBiryukov 6 years ago.

Download all attachments as: .zip

Change History (11)

#1 @c3mdigital
6 years ago

  • Keywords needs-patch added
  • Version set to 2.3

Inline docs need to better explain the error handling. Function returns WP_Error object.

Current Inline doc:

/**
 * Adds a new term to the database. Optionally marks it as an alias of an existing term.
 *
 * Error handling is assigned for the nonexistence of the $taxonomy and $term
 * parameters before inserting. If both the term id and taxonomy exist
 * previously, then an array will be returned that contains the term id and the
 * contents of what is returned. The keys of the array are 'term_id' and
 * 'term_taxonomy_id' containing numeric values.
 *
 * It is assumed that the term does not yet exist or the above will apply. The
 * term will be first added to the term table and then related to the taxonomy
 * if everything is well. If everything is correct, then several actions will be
 * run prior to a filter and then several actions will be run after the filter
 * is run.
 *
 * The arguments decide how the term is handled based on the $args parameter.
 * The following is a list of the available overrides and the defaults.
 *
 * 'alias_of'. There is no default, but if added, expected is the slug that the
 * term will be an alias of. Expected to be a string.
 *
 * 'description'. There is no default. If exists, will be added to the database
 * along with the term. Expected to be a string.
 *
 * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value
 * of 'parent' to the term.
 *
 * 'slug'. Expected to be a string. There is no default.
 *
 * If 'slug' argument exists then the slug will be checked to see if it is not
 * a valid term. If that check succeeds (it is not a valid term), then it is
 * added and the term id is given. If it fails, then a check is made to whether
 * the taxonomy is hierarchical and the parent argument is not empty. If the
 * second check succeeds, the term will be inserted and the term id will be
 * given.
 *
 * @package WordPress
 * @subpackage Taxonomy
 * @since 2.3.0
 * @uses $wpdb
 *
 * @uses apply_filters() Calls 'pre_insert_term' hook with term and taxonomy as parameters.
 * @uses do_action() Calls 'create_term' hook with the term id and taxonomy id as parameters.
 * @uses do_action() Calls 'create_$taxonomy' hook with term id and taxonomy id as parameters.
 * @uses apply_filters() Calls 'term_id_filter' hook with term id and taxonomy id as parameters.
 * @uses do_action() Calls 'created_term' hook with the term id and taxonomy id as parameters.
 * @uses do_action() Calls 'created_$taxonomy' hook with term id and taxonomy id as parameters.
 *
 * @param string $term The term to add or update.
 * @param string $taxonomy The taxonomy to which to add the term
 * @param array|string $args Change the values of the inserted term
 * @return array|WP_Error The Term ID and Term Taxonomy ID
 */

#2 @SergeyBiryukov
6 years ago

  • Milestone changed from Awaiting Review to 3.7

@DrewAPicture
6 years ago

docblock redo

#3 @DrewAPicture
6 years ago

  • Keywords has-patch added; needs-patch removed

22801.diff rewrites big parts of this docblock for clarity, including the change about returning a WP_Error object mentioned in the ticket description.

Side note: this whole file is slated for a docs review anyway.

@DrewAPicture
6 years ago

tense, wrapping

#4 @SergeyBiryukov
6 years ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from new to closed

In 25489:

Update inline documentation for wp_insert_term().

props DrewAPicture.
fixes #22801.

@lgedeon
6 years ago

Alternate list of of error triggers, and tense fix typo fix

#5 @lgedeon
6 years ago

Tried to follow the order of error triggers in the code, and also fixed a typo.

#6 @SergeyBiryukov
6 years ago

Looks like I used 22801.diff in [25489] instead of 22801.2.diff.

22801.4.diff is a partial refresh of 22801.2.diff and 22801.3.diff against trunk, and is my take on further clarifying the error handling.

  • A numeric $term is allowed, as long as it's not empty.
  • A non-unique slug is also allowed (it will be regenerated), as long as the name is different.
Last edited 6 years ago by SergeyBiryukov (previous) (diff)

#7 @DrewAPicture
6 years ago

In 25498:

Clarify error handling and special cases in the wp_insert_term() phpdoc block.

props lgedeon, SergeyBiryukov. See #22801.

Note: See TracTickets for help on using tickets.