WordPress.org

Description

This function inserts links or updates links. It runs all necessary sanitizing, provides default values if arguments are missing and finally saves the link. It takes a single array of arguments and returns the new link ID on success.

You can turn error reporting on with the second, optional argument. By default, they're off.

Usage

<?php wp_insert_link( $linkdata, true ); ?>

Example

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.

<?php
    $linkdata = array(
	'link_name' => 'WordPress Codex',
	'link_url' => 'http://codex.wordpress.org'
    );

    $link_id = wp_insert_link( $linkdata );
?>

wp_insert_link will update a link - instead of inserting it - if you provide the link's ID.

<?php
    $linkdata = array(
	'link_id' => 7,
	'link_name' => 'WordPress Codex',
	'link_url' => 'http://codex.wordpress.org'
    );

    $link_id = wp_insert_link( $linkdata );
?>

Parameters

$linkdata

(array) (required) An array containing the key/value pairs for the new link. The $key corresponds to the wp_links database table.

Default: None

Important: Specifying the link ID 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 array. Only link_name and link_url must be specified for the link to be successfully saved.

<?php
$linkdata = array(
	"link_id"		=> 0, // integer, if updating, the ID of the existing link
	"link_url"		=> '', // varchar, the URL the link points to
	"link_name"		=> '', // varchar, the title of the link
	"link_image"		=> '', // varchar, a URL of an image
	"link_target"		=> '', // varchar, the target element for the anchor tag
	"link_description"	=> '', // varchar, a short description of the link
	"link_visible"		=> 'Y', // varchar, Y means visible, anything else means not
	"link_owner"		=> '', // integer, a user ID
	"link_rating"		=> 0, // integer, a rating for the link
	"link_updated"		=> '0000-00-00 00:00:00', // datetime, when the link was last updated
	"link_rel"		=> '', // varchar, a relationship of the link to you
	"link_notes"		=> '', // text, an extended description of or notes on the link
	"link_rss"		=> '', // varchar, a URL of an associated RSS feed
	"link_category"		=> '' // int, the term ID of the link category. if empty, uses default link category
);
?>

$wp_error

(boolean) (optional) Returns an error through WP_Error along with any errors generated by the database

Default: false

Return

The ID of the link (whether new or updated) on success.

On error, 0 if $wp_error is set to false. A WP_Error object if it is set to true.

Source File

wp_insert_link() is located in wp-admin/includes/bookmark.php.