wp_insert_link( array $linkdata, bool $wp_error = false )
Inserts a link into the database, or updates an existing link.
Contents
Description Description
Runs all the necessary sanitizing, provides default values if arguments are missing, and finally saves the link.
Parameters Parameters
- $linkdata
-
(array) (Required) Elements that make up the link to insert.
- 'link_id'
(int) Optional. The ID of the existing link if updating. - 'link_url'
(string) The URL the link points to. - 'link_name'
(string) The title of the link. - 'link_image'
(string) Optional. A URL of an image. - 'link_target'
(string) Optional. The target element for the anchor tag. - 'link_description'
(string) Optional. A short description of the link. - 'link_visible'
(string) Optional. 'Y' means visible, anything else means not. - 'link_owner'
(int) Optional. A user ID. - 'link_rating'
(int) Optional. A rating for the link. - 'link_updated'
(string) Optional. When the link was last updated. - 'link_rel'
(string) Optional. A relationship of the link to you. - 'link_notes'
(string) Optional. An extended description of or notes on the link. - 'link_rss'
(string) Optional. A URL of an associated RSS feed. - 'link_category'
(int) Optional. The term ID of the link category. If empty, uses default link category.
- 'link_id'
- $wp_error
-
(bool) (Optional) Whether to return a WP_Error object on failure.
Default value: false
Return Return
(int|WP_Error) Value 0 or WP_Error on failure. The link ID on success.
More Information More Information
- Specifying the link_id value for $linkdata array will update any link that exists with that ID. If that ID does not exist, the ID will be disregarded and a new link will be created.
- You can specify as much as you’d like within the $linkdata array. Only link_name and link_url must be specified for the link to be successfully saved.
Source Source
File: wp-admin/includes/bookmark.php
function wp_insert_link( $linkdata, $wp_error = false ) { global $wpdb; $defaults = array( 'link_id' => 0, 'link_name' => '', 'link_url' => '', 'link_rating' => 0, ); $parsed_args = wp_parse_args( $linkdata, $defaults ); $parsed_args = wp_unslash( sanitize_bookmark( $parsed_args, 'db' ) ); $link_id = $parsed_args['link_id']; $link_name = $parsed_args['link_name']; $link_url = $parsed_args['link_url']; $update = false; if ( ! empty( $link_id ) ) { $update = true; } if ( '' === trim( $link_name ) ) { if ( '' !== trim( $link_url ) ) { $link_name = $link_url; } else { return 0; } } if ( '' === trim( $link_url ) ) { return 0; } $link_rating = ( ! empty( $parsed_args['link_rating'] ) ) ? $parsed_args['link_rating'] : 0; $link_image = ( ! empty( $parsed_args['link_image'] ) ) ? $parsed_args['link_image'] : ''; $link_target = ( ! empty( $parsed_args['link_target'] ) ) ? $parsed_args['link_target'] : ''; $link_visible = ( ! empty( $parsed_args['link_visible'] ) ) ? $parsed_args['link_visible'] : 'Y'; $link_owner = ( ! empty( $parsed_args['link_owner'] ) ) ? $parsed_args['link_owner'] : get_current_user_id(); $link_notes = ( ! empty( $parsed_args['link_notes'] ) ) ? $parsed_args['link_notes'] : ''; $link_description = ( ! empty( $parsed_args['link_description'] ) ) ? $parsed_args['link_description'] : ''; $link_rss = ( ! empty( $parsed_args['link_rss'] ) ) ? $parsed_args['link_rss'] : ''; $link_rel = ( ! empty( $parsed_args['link_rel'] ) ) ? $parsed_args['link_rel'] : ''; $link_category = ( ! empty( $parsed_args['link_category'] ) ) ? $parsed_args['link_category'] : array(); // Make sure we set a valid category. if ( ! is_array( $link_category ) || 0 === count( $link_category ) ) { $link_category = array( get_option( 'default_link_category' ) ); } if ( $update ) { if ( false === $wpdb->update( $wpdb->links, compact( 'link_url', 'link_name', 'link_image', 'link_target', 'link_description', 'link_visible', 'link_owner', 'link_rating', 'link_rel', 'link_notes', 'link_rss' ), compact( 'link_id' ) ) ) { if ( $wp_error ) { return new WP_Error( 'db_update_error', __( 'Could not update link in the database.' ), $wpdb->last_error ); } else { return 0; } } } else { if ( false === $wpdb->insert( $wpdb->links, compact( 'link_url', 'link_name', 'link_image', 'link_target', 'link_description', 'link_visible', 'link_owner', 'link_rating', 'link_rel', 'link_notes', 'link_rss' ) ) ) { if ( $wp_error ) { return new WP_Error( 'db_insert_error', __( 'Could not insert link into the database.' ), $wpdb->last_error ); } else { return 0; } } $link_id = (int) $wpdb->insert_id; } wp_set_link_cats( $link_id, $link_category ); if ( $update ) { /** * Fires after a link was updated in the database. * * @since 2.0.0 * * @param int $link_id ID of the link that was updated. */ do_action( 'edit_link', $link_id ); } else { /** * Fires after a link was added to the database. * * @since 2.0.0 * * @param int $link_id ID of the link that was added. */ do_action( 'add_link', $link_id ); } clean_bookmark_cache( $link_id ); return $link_id; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
2.0.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Basic Usage
wp_insert_link() requires an array of arguments. Only two of the arguments must be provided – link_name and link_url. The rest are optional.
Update a link
wp_insert_link() will update a link – instead of inserting it – if you provide the link’s ID.
Feedback
This does not work for me. Instead, I have to use wp_update_link(). — By Babak Fakhamzadeh —