Administration: Introduce wp_get_admin_notice() and wp_admin_notice().

[costdev]

Overview

This introduces two new functions to standardize admin notice output and reduce maintenance.

• wp_get_admin_notice() - Returns the markup for an admin notice.
• wp_admin_notice() - Outputs an admin notice.

Parameters

The functions accept the following parameters:

• string $message - The message for the admin notice.
• array $args - Optional. Arguments for the admin notice. Default empty array.
  • string $type - Optional. The type of the admin notice. e.g. 'success', 'warning', 'info'. Default empty string.
  • bool $dismissible - Optional. Whether the admin notice is dismissible. Default false.
  • string $id - Optional. The ID for the admin notice. Default empty string.
  • string[] $additional_classes - Optional. A string array of class names. Default empty array.
  • bool $paragraph_wrap - Optional. Whether to wrap the message in paragraph tags. Default true.

Filters

wp_get_admin_notice has the following filters:

• wp_admin_notice_args - Filters the arguments for the admin notice.
  • Passes (array) $args, (string) $message.
• wp_admin_notice_markup - Filters the markup for the admin notice.
  • Passes (string) $markup, (string) $message, (array) $args.

Actions

wp_admin_notice has the following action:

• wp_admin_notice - Fires before an admin notice is output.
  • Passes (string) $message, (array) $args.

Tests

PHPUnit tests are included and achieve 100% line and branch coverage.

Examples

Get the markup for a dismissible success notice

$markup = wp_get_admin_notice( 'Success!', array( 'type' => 'success', 'dismissible' => true ) );

Result:

$markup = '<div class="notice notice-success is-dismissible"><p>Success!</p></div>';

---

Output a dismissible success notice

wp_admin_notice( 'Success!', array( 'type' => 'success', 'dismissible' => true ) );

Output:

<div class="notice notice-success is-dismissible"><p>Success!</p></div>

---

Make all admin notices dismissible

add_filter( 'wp_admin_notice_args', 'make_admin_notices_dismissible' );
function make_admin_notices_dismissible( $args ) {
    $args['dismissible'] = true;
    return $args;
}

wp_admin_notice( 'A notice that is forcibly dismissible.', array( 'dismissible' => false ) );

Output:

<div class="notice is-dismissible"><p>A notice that is forcibly dismissible.</p><button type="button" class="notice-dismiss"><span class="screen-reader-text">Dismiss this notice.</span></button></div>

---

Add a custom class to all admin notices

add_filter( 'wp_admin_notice_args', 'add_custom_class_to_admin_notices' );
function add_custom_class_to_admin_notices( $args ) {
    $args['additional_classes'][] = 'custom-class';
    return $args;
}

wp_admin_notice( 'A notice with a custom class.' );

Output:

<div class="notice custom-class"><p>A notice with a custom class.</p></div>

---

Log warning notices

add_action( 'wp_admin_notice', 'log_warning_admin_notices', 10, 2 );
function log_warning_admin_notices( $message, $args ) {
    if ( 'warning' === $args['type'] ) {
        error_log( $message );
    }
}

https://core.trac.wordpress.org/ticket/57791

[joedolson]

In https://core.trac.wordpress.org/changeset/56408