WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp insert link

This article is marked as in need of editing. You can help Codex by editing it.
English

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$linkdatatrue ); ?>

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.