@wordpress/deprecated

What is @wordpress/deprecated?

@wordpress/deprecated is a utility package used in WordPress development to handle deprecated features. It provides a way to mark functions, methods, or other features as deprecated, allowing developers to notify users of the deprecation and suggest alternatives.

What are @wordpress/deprecated's main functionalities?

Marking a function as deprecated

This feature allows developers to mark a function as deprecated. The `deprecated` function is called with the name of the deprecated function, the version since it is deprecated, an alternative function, and the plugin name. This helps in notifying users about the deprecation and suggesting an alternative.

const deprecated = require('@wordpress/deprecated');

function oldFunction() {
  deprecated('oldFunction', {
    version: '1.0.0',
    alternative: 'newFunction',
    plugin: 'my-plugin'
  });
  // Function logic
}

Other packages similar to @wordpress/deprecated

util-deprecate

The `util-deprecate` package is a Node.js utility that provides a similar functionality to mark functions as deprecated. It is a lightweight solution that outputs a warning message when a deprecated function is called. Compared to @wordpress/deprecated, it is more general-purpose and not specifically tailored for WordPress development.

depd

The `depd` package is another Node.js utility for deprecating functions and methods. It provides a way to mark functions as deprecated and outputs a warning message when they are used. Like `util-deprecate`, it is not specific to WordPress but serves a similar purpose in notifying developers and users about deprecated features.

README

Deprecated

Deprecation utility for WordPress. Logs a message to notify developers about a deprecated feature.

Installation

Install the module

npm install @wordpress/deprecated --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Hook

The deprecated action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.

Example:

import { addAction } from '@wordpress/hooks';

function addDeprecationAlert( message, { version } ) {
	alert( `Deprecation: ${ message }. Version: ${ version }` );
}

addAction(
	'deprecated',
	'my-plugin/add-deprecation-alert',
	addDeprecationAlert
);

API

default

Logs a message to notify developers about a deprecated feature.

Usage

import deprecated from '@wordpress/deprecated';

deprecated( 'Eating meat', {
	since: '2019.01.01'
	version: '2020.01.01',
	alternative: 'vegetables',
	plugin: 'the earth',
	hint: 'You may find it beneficial to transition gradually.',
} );

// Logs: 'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'

Parameters

• feature string: Name of the deprecated feature.
• options [Object]: Personalisation options
• options.since [string]: Version in which the feature was deprecated.
• options.version [string]: Version in which the feature will be removed.
• options.alternative [string]: Feature to use instead
• options.plugin [string]: Plugin name if it's a plugin feature
• options.link [string]: Link to documentation
• options.hint [string]: Additional message to help transition away from the deprecated feature.

logged

Object map tracking messages which have been logged, for use in ensuring a message is only logged once.

Type

• Record<string, true | undefined>

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.