Remove Link/Bookmark API form Core: Phase 2

[desrosj]

In WordPress 3.5, the Link Manager was disabled in Core by default in new installs, and hidden entirely when no links were present on a site updating (see #21307).

The intention was to return to this later and remove the Bookmark/Links API from Core entirely. However, no one returned to that second phase. This ticket is to explore removing this long hidden API from Core.

[desrosj]

Here is some fact finding and rough back of napkin thoughts in no particular order:

• It's been 10+ years now since #21307.
• There are just under 50,000 sites with the ​Links Manager plugin active.
• Moving all related code into the plugin and releasing an update seems like an easy way to somewhat seamlessly make these changes, given the site is using the plugin to re-enable the feature (the plugin is currently a 1 line add_filter()).
• Sites have had 10 years to activate this plugin if they truly want this functionality. It's safe to say the overwhelming majority of sites that want this feature have this plugin active.
• Only ​1 theme and ​50 plugins have the pre_option_link_manager_enabled filter. Only 3 have 10k active installs (Link Manager is first with ~50k).
• Some searches of the plugin directory show that calling the related functions in the wild is not 0, but also not significant (lots of these results are either false positives, or custom implementations):
  • get_bookmark(): ​67 plugins, 107 matches, 5 over 50k installs.
  • get_bookmarks(): ​176 plugins, 402 instances, 4 over 50k installs.
  • Loading wp-admin/includes/bookmark.php directly: ​87 plugins, 488 instances, 2 over 50k installs.

It seems reasonable to:

• Move all related functionality into a new release of the Link Manager plugin defensively with the use of (function|class)_exists() checks.
• Add a notice within the dashboard for users with the activate_plugins capability when the Link API appears to be active and links exist that they should update the plugin.
• Potentially add _deprecated_function() notices to the related functions when the Link Manager is not active and at the correct version recommending the user installs or updates the plugin.
• Publish developer notes and an awareness campaign to make folks aware this will happen.
• Allow 1 full major release to pass before removing all related code from Core.
• Remove the functions from Core in a following release.

[desrosj]

Also, this should be accompanied by a proposal posted to Making WordPress Core, which I intend to draft in the coming weeks.

[johnbillion]

+1 on all the points in your proposal.

[desrosj]

I'm moving this to 6.1. I'd like to get this done sooner rather than later to avoid what happened previously.

[jrf]

Sites have had 10 years to activate this plugin if they truly want this functionality. It's safe to say the overwhelming majority of sites that want this feature have this plugin active.

To be honest, it's the first I've ever heard of the plugin and for "old" sites which were using the functionality when the API was deprecated, the option was turned back on automatically, so they never had the need to install the plugin.

I don't remember ever seeing a notice about turning on the plugin in the dashboard either, so I suspect there are a lot more sites out there which still use the API and have no clue that they were expected to turn on a plugin.

As site-owners often skip a number of WP releases when updating, I think only allowing one major with the dashboard notice is cutting things a little too fine.

That is, of course, unless the dashboard notification telling people to turn on the plugin is backported all the way back to WP 3.7.

[desrosj]

Replying to jrf:

I don't remember ever seeing a notice about turning on the plugin in the dashboard either, so I suspect there are a lot more sites out there which still use the API and have no clue that they were expected to turn on a plugin.

As site-owners often skip a number of WP releases when updating, I think only allowing one major with the dashboard notice is cutting things a little too fine.

That is, of course, unless the dashboard notification telling people to turn on the plugin is backported all the way back to WP 3.7.

I was thinking of going the opposite way. Instead of backporting the notice, the first major release after moving the necessary code to the plugin would include an admin notice that displays when sites appear to be using the API without the plugin instructing them to install the plugin because the API will be removed in a future release. Paired with __deprecated_function() notices, this would hopefully be enough feedback/heads up.

Totally open to waiting more than 1 release if that's the consensus. But I think the approach I described above could allow for 1 or 2 major releases.

Time is running out on 6.1, though, so I'm going to focus on this next release.

[mukesh27]

This ticket was discussed in the recent bug scrub.

Ticket need feedback from the dev so added the workflow keyword.

Props to @costdev

[desrosj]

I haven't been able to give this the attention it needs so far this cycle. Going to punt to Future Release until some progress can be made.

[aristath]

+1 from me.
WP includes a lot of functionality that hasn't been used in many years, and we should be doing some house cleaning.
We should find a viable strategy to remove code like this... Deprecating functions and adding an admin notice sounds reasonable to me

[jrf]

Just a heads-up: I just wanted to try and install the plugin on a site which is still using the Links module, but as the plugin hasn't been updated in 11 (!!!) years, it will not show up when a user searches for it from the WP admin panel.

Of course, I can download the plugin and then install it via an upload or via FTP, but that's besides the point.

What my point really is, is that the plugin hasn't been updated in 11 year.

This raises the following questions:

1. Will the plugin as-is still work with WP 6.2+ ?
2. Will the plugin as-is still work with more recent PHP versions ? (think: PHP 5.5 and higher as PHP 5.5 wasn't released yet 11 years ago...)

Additionally, I worry that an official recommendation to install a plugin which hasn't had an update in 11 years, would undermine all efforts which try to teach admins to look critically whether plugins are still maintained etc to prevent security issues.

I believe that at the very least we should make sure the plugin gets a thorough once over for WP and PHP compatibility issues and a new point release, which will allow end-user admins to install the plugin from the comfort of the admin dashboard.

I'd also recommend that the plugin be set up with a repo on GitHub to allow for future maintenance of it in a more accessible way.

[jrf]

Ouch.. also just realised that the officially available version is 0.1-beta which also doesn't instill much confidence...

[jrf]

Never mind... I just realize I overlooked the following line:

the plugin is currently a 1 line add_filter()

In other words, the plugin needs to be build properly before any other action can be taken.

[georgestephanis]

Started roughing in a full abstraction of the links functionality out to a standalone plugin -- ​https://github.com/georgestephanis/wp-links -- if worthwhile I'm fine merging it in with nacin's old one-filter-line plugin, and on updates autoinstalling the plugin if the site is using links to continue that functionality.

I've been doing some other experiments testing how well it holds up to modern wp as well. I'd like to see if we can explore it further outside of core once the code gets yoinked -- hopefully this will enable progress on that front.

### Related: #56362

Step 1 of that ticket's rollout plan — moving the Link Manager functionality into a plugin defensively — is done: ​https://github.com/georgestephanis/wp-links reproduces this API under the same function/class names, guarded so it activates only once core stops providing them.

This PR is step 2: flag everything as deprecated, with no behavior change. _deprecated_function(), _deprecated_class(), and _deprecated_file() only emit a notice when WP_DEBUG is on — every function, class, and admin page here keeps working exactly as it does today. This should be safe to merge well ahead of any actual removal, giving plugin/theme authors real advance notice.

## What's deprecated

Matches the companion plugin's coverage:

• get_bookmark(), get_bookmark_field(), get_bookmarks(), sanitize_bookmark(), sanitize_bookmark_field(), clean_bookmark_cache()
• wp_list_bookmarks()
• get_edit_bookmark_link(), edit_bookmark_link() (in the otherwise-generic wp-includes/link-template.php, but part of this API surface)
• add_link(), edit_link(), get_default_link_to_edit(), wp_delete_link(), wp_get_link_cats(), get_link_to_edit(), wp_insert_link(), wp_set_link_cats(), wp_update_link()
• wp_link_category_checklist()
• WP_Links_List_Table, WP_Widget_Links (via _deprecated_class() in each constructor)
• wp-admin/link-manager.php, link.php, link-add.php, edit-link-form.php, link-parse-opml.php, wp-links-opml.php (via _deprecated_file())

Every deprecation message points at installing the companion plugin — there's no in-core replacement function to name, since the point is this functionality moving out of core entirely.

## Deliberately not touched here

Matches what the companion plugin doesn't cover either — tracked in its ​issue #1 and ​issue #2:

• The link_category taxonomy registration and manage_links capability mapping — no established core convention for deprecating a taxonomy or capability at runtime the way there is for functions/classes/files
• The Links menu entries
• The five link_*_meta_box() functions and xfn_check() — internal render callbacks for the now-deprecated edit-link-form.php; deprecating them individually seemed redundant with deprecating that file
• The two Links-specific AJAX handlers
• The wp_links DB table, link.js/xfn.js
• The already-19-years-deprecated stubs in wp-includes/deprecated.php

## How this was verified

Not just PHP lint — tested against a real WordPress environment (WP Playground): link category creation, link insertion, get_bookmarks(), wp_list_bookmarks() rendering, and widget instantiation all still succeed exactly as before, while each one correctly emits a PHP_DEPRECATED-level notice under WP_DEBUG.

[georgestephanis]

(for what it's worth, I'm 100% happy to transfer the wp-links repo I made over to the WordPress organization if it's to be a canonical plugin that core directs folks to)

### Related: #56362

This is a preview/reference patch, not proposed for merging as-is. #56362's own rollout plan puts a full removal as the *last* of five phased steps — after deprecation notices ship in a release and a full cycle passes. Opening this to make that eventual step concrete and grounded in real code, alongside a working standalone plugin that already polyfills everything removed here: ​https://github.com/georgestephanis/wp-links

That plugin reproduces this functionality under the same function/class names, each guarded with function_exists()/class_exists() (or an equivalent technique where a guard doesn't directly apply — see its README for the specifics), so it activates dormant on a normal install and takes over the moment core stops providing this.

## Scope

Matches the companion plugin's current coverage exactly — the API functions/classes, the link_category taxonomy and manage_links capability, the admin pages, the widget, and OPML. Deliberately not touched here, tracked in ​issue #1 and ​issue #2 of that repo:

• The wp_links DB table creation in wp-admin/includes/schema.php
• wp-admin/js/link.js / xfn.js and their registrations
• The ~10 already-19-years-deprecated Links functions in wp-includes/deprecated.php (get_linksbyname(), wp_get_links(), etc.) — these call into functions removed here and would fatal if ever invoked; a real patch needs to either remove them too or give them a graceful no-op
• The PHPUnit test suite (tests/phpunit/tests/link*.php, bookmark/*)

## Worth flagging from putting this together

• wp-includes/bookmark.php / bookmark-template.php are required unconditionally in wp-settings.php — not guarded the way most of core's Links code is. Deleting the files without also removing those two lines breaks the bootstrap entirely. Only caught by actually booting a build, not by review — see the "How this was verified" note below.
• wp_ajax_add_link_category() and wp_ajax_delete_link() in wp-admin/includes/ajax-actions.php aren't reproduced by the companion plugin (its own known gap), but leaving them in core while removing the functions they call (get_taxonomy('link_category'), get_bookmark(), wp_delete_link()) would leave two guaranteed-fatal AJAX handlers behind, so they're removed here too rather than left dangling.
• A stray wp_list_bookmarks() call in the default theme-compat fallback sidebar (wp-includes/theme-compat/sidebar.php) needed removing as well.

## How this was verified

Not just PHP lint — tested against a real WordPress environment (WP Playground) two ways:

1. A normal install boots and runs fine with everything in this diff removed.
2. With the ​companion plugin active on top of that stripped install: link category creation, link insert/list, front-end wp_list_bookmarks() rendering, and the admin list-table page all work exactly as before, entirely through the plugin's polyfills.

Companion preview PR showing what the eventual final removal (step 5 of #56362's plan) would look like on top of this deprecation: #13360

Opened alongside a real, mergeable deprecation-only PR for the intermediate steps of #56362's plan (no behavior change, just notices): #13358