222 lines
8.5 KiB
PHP
222 lines
8.5 KiB
PHP
|
<?php
|
||
|
|
/**
|
||
|
|
* The one admin menu the manager plugins share.
|
||
|
|
*
|
||
|
|
* ┌──────────────────────────────────────────────────────────────────────────┐
|
||
|
|
* │ THIS FILE IS BYTE-IDENTICAL IN EVERY MANAGER PLUGIN. │
|
||
|
|
* │ Do not edit it to add something for one plugin. Extend it through the │
|
||
|
|
* │ `wpmgr_dashboard_cards` filter, which is what it is for. │
|
||
|
|
* │ Contract version 1.0.0 — frozen. See "Why it is frozen" below. │
|
||
|
|
* └──────────────────────────────────────────────────────────────────────────┘
|
||
|
|
*
|
||
|
|
* The problem it solves: five plugins from the same family, each adding a
|
||
|
|
* top-level menu, is five entries in a sidebar that already has fifteen. So
|
||
|
|
* they share one parent, "Manager", and each adds a submenu under it.
|
||
|
|
*
|
||
|
|
* Three things about how it does that are load-bearing, and none is obvious.
|
||
|
|
*
|
||
|
|
* **1. Every declaration is guarded.** Five plugins each `require_once` their
|
||
|
|
* own copy of this file, in one request. `require_once` only deduplicates by
|
||
|
|
* resolved path, and these are five different paths — so without the
|
||
|
|
* `function_exists()` guard, activating the second plugin is
|
||
|
|
* `Fatal error: Cannot redeclare wpmgr_ensure_menu()`. A white screen on a
|
||
|
|
* shop, caused by nothing except owning two of these plugins. It is the same
|
||
|
|
* shape as the update-hook collision: a fault that exists only when there is
|
||
|
|
* more than one, which means no repository's own tests can find it.
|
||
|
|
*
|
||
|
|
* **2. Whichever copy loads first wins, and that order is arbitrary** — it is
|
||
|
|
* plugin activation order, effectively alphabetical by directory. PHP cannot
|
||
|
|
* un-declare a function, so there is no honest way for a newer copy to replace
|
||
|
|
* an older one that has already been loaded. The only stable answer is that
|
||
|
|
* the file never changes. Hence: **frozen**. The parent slug, the capability,
|
||
|
|
* the position and the filter name are a contract between five repositories
|
||
|
|
* now, and anything new arrives through the filter.
|
||
|
|
*
|
||
|
|
* **3. The dashboard is built from a filter, not owned by a plugin.** If the
|
||
|
|
* plugin that happened to register the menu is deactivated, the menu is
|
||
|
|
* re-registered by the next one on the following request and the page still
|
||
|
|
* renders — because the page's content comes from whoever is installed, not
|
||
|
|
* from whoever created it. Registering a callback that lives in one plugin
|
||
|
|
* would mean deactivating that plugin takes the other four's screens with it.
|
||
|
|
*
|
||
|
|
* Each plugin calls `wpmgr_ensure_menu()` at the top of its own `admin_menu`
|
||
|
|
* callback, before its own `add_submenu_page( 'wpmgr', … )`. Not on some other
|
||
|
|
* hook: `add_submenu_page` against a parent that does not exist yet silently
|
||
|
|
* fails, and whose `admin_menu` runs first is, again, arbitrary.
|
||
|
|
*
|
||
|
|
* The package below is the family, not any one plugin: this file is
|
||
|
|
* byte-identical in five repositories, and a tag naming whichever of them it
|
||
|
|
* was first written in reads as a mistake in the other four — which invites
|
||
|
|
* somebody to "fix" it, in one repository, which is the exact edit the freeze
|
||
|
|
* exists to prevent.
|
||
|
|
*
|
||
|
|
* @package WordPress_Manager_Family
|
||
|
|
*/
|
||
|
|
|
||
|
|
if ( ! defined( 'ABSPATH' ) ) {
|
||
|
|
exit;
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( ! defined( 'WPMGR_MENU_VERSION' ) ) {
|
||
|
|
define( 'WPMGR_MENU_VERSION', '1.0.0' );
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( ! defined( 'WPMGR_MENU_SLUG' ) ) {
|
||
|
|
define( 'WPMGR_MENU_SLUG', 'wpmgr' );
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( ! function_exists( 'wpmgr_ensure_menu' ) ) {
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Register the shared parent menu, unless somebody already has.
|
||
|
|
*
|
||
|
|
* Call this first thing in your own `admin_menu` callback.
|
||
|
|
*/
|
||
|
|
function wpmgr_ensure_menu() {
|
||
|
|
global $admin_page_hooks;
|
||
|
|
|
||
|
|
if ( isset( $admin_page_hooks[ WPMGR_MENU_SLUG ] ) ) {
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The label on the shared parent menu.
|
||
|
|
*
|
||
|
|
* Left untranslated here on purpose: this file is byte-identical in
|
||
|
|
* five plugins, so it cannot carry any one of their text domains, and
|
||
|
|
* a string with the wrong domain is a string that is silently never
|
||
|
|
* translated. Any plugin may translate it in its own domain through
|
||
|
|
* this filter.
|
||
|
|
*
|
||
|
|
* @param string $title The menu title.
|
||
|
|
*/
|
||
|
|
$title = apply_filters( 'wpmgr_menu_title', 'Manager' );
|
||
|
|
|
||
|
|
add_menu_page(
|
||
|
|
$title,
|
||
|
|
$title,
|
||
|
|
'manage_options',
|
||
|
|
WPMGR_MENU_SLUG,
|
||
|
|
'wpmgr_render_dashboard',
|
||
|
|
'dashicons-admin-generic',
|
||
|
|
// Just below WooCommerce (55.x) and above Appearance (60). The
|
||
|
|
// fractional position is not decoration: an integer collides with
|
||
|
|
// whatever core or another plugin put there, and the loser is
|
||
|
|
// simply dropped.
|
||
|
|
58.9
|
||
|
|
);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The shared landing page.
|
||
|
|
*
|
||
|
|
* Nothing here knows which plugins exist. Every card comes from the
|
||
|
|
* filter, so the page is correct whichever of them registered the menu and
|
||
|
|
* whichever of them have since been deactivated.
|
||
|
|
*/
|
||
|
|
function wpmgr_render_dashboard() {
|
||
|
|
if ( ! current_user_can( 'manage_options' ) ) {
|
||
|
|
wp_die( esc_html( 'You do not have permission to view this page.' ) );
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Cards on the shared dashboard, one per installed manager plugin.
|
||
|
|
*
|
||
|
|
* Each entry:
|
||
|
|
* title string Plugin name, already translated by its owner.
|
||
|
|
* status string 'ok' | 'warn' | 'fail' — what the check said.
|
||
|
|
* headline string One short line: the number that matters.
|
||
|
|
* lines array label => value, a handful at most.
|
||
|
|
* url string Where "Open" goes.
|
||
|
|
* colour string The plugin's own colour, as #rrggbb.
|
||
|
|
*
|
||
|
|
* Implementations must not measure anything here. This filter runs on
|
||
|
|
* an admin page load; a card that walks the disk or makes an HTTP
|
||
|
|
* request turns somebody else's dashboard into a slow page, and they
|
||
|
|
* will not know why.
|
||
|
|
*
|
||
|
|
* @param array $cards The cards so far.
|
||
|
|
*/
|
||
|
|
$cards = apply_filters( 'wpmgr_dashboard_cards', array() );
|
||
|
|
|
||
|
|
echo '<div class="wrap wpmgr-dashboard">';
|
||
|
|
echo '<h1>' . esc_html( apply_filters( 'wpmgr_menu_title', 'Manager' ) ) . '</h1>';
|
||
|
|
|
||
|
|
if ( empty( $cards ) ) {
|
||
|
|
echo '<p>Nothing to report.</p></div>';
|
||
|
|
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
echo '<style>'
|
||
|
|
. '.wpmgr-cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:16px;margin-top:20px}'
|
||
|
|
. '.wpmgr-card{background:#fff;border:1px solid #dcdcde;border-radius:8px;padding:0;overflow:hidden}'
|
||
|
|
. '.wpmgr-card header{padding:14px 18px;color:#fff;display:flex;justify-content:space-between;align-items:center}'
|
||
|
|
. '.wpmgr-card header h2{margin:0;font-size:14px;color:inherit}'
|
||
|
|
. '.wpmgr-card .wpmgr-body{padding:16px 18px}'
|
||
|
|
. '.wpmgr-headline{font-size:22px;font-weight:600;margin:0 0 10px}'
|
||
|
|
. '.wpmgr-card dl{display:grid;grid-template-columns:1fr auto;gap:4px 12px;margin:0;font-size:13px}'
|
||
|
|
. '.wpmgr-card dt{color:#646970;margin:0}.wpmgr-card dd{margin:0;text-align:right}'
|
||
|
|
. '.wpmgr-state{font-size:11px;text-transform:uppercase;letter-spacing:.04em;'
|
||
|
|
. 'background:rgba(255,255,255,.22);padding:2px 8px;border-radius:10px}'
|
||
|
|
. '.wpmgr-card footer{padding:12px 18px;border-top:1px solid #f0f0f1}'
|
||
|
|
. '</style>';
|
||
|
|
|
||
|
|
echo '<div class="wpmgr-cards">';
|
||
|
|
|
||
|
|
$states = array(
|
||
|
|
'ok' => 'OK',
|
||
|
|
'warn' => 'Attention',
|
||
|
|
'fail' => 'Action needed',
|
||
|
|
);
|
||
|
|
|
||
|
|
foreach ( $cards as $card ) {
|
||
|
|
if ( empty( $card['title'] ) ) {
|
||
|
|
continue;
|
||
|
|
}
|
||
|
|
|
||
|
|
$colour = isset( $card['colour'] ) && preg_match( '/^#[0-9a-f]{6}$/i', $card['colour'] )
|
||
|
|
? $card['colour']
|
||
|
|
: '#50575e';
|
||
|
|
|
||
|
|
$status = isset( $card['status'] ) && isset( $states[ $card['status'] ] ) ? $card['status'] : 'ok';
|
||
|
|
|
||
|
|
echo '<section class="wpmgr-card">';
|
||
|
|
printf(
|
||
|
|
'<header style="background:%s"><h2>%s</h2><span class="wpmgr-state">%s</span></header>',
|
||
|
|
esc_attr( $colour ),
|
||
|
|
esc_html( $card['title'] ),
|
||
|
|
esc_html( $states[ $status ] )
|
||
|
|
);
|
||
|
|
|
||
|
|
echo '<div class="wpmgr-body">';
|
||
|
|
|
||
|
|
if ( ! empty( $card['headline'] ) ) {
|
||
|
|
echo '<p class="wpmgr-headline">' . esc_html( $card['headline'] ) . '</p>';
|
||
|
|
}
|
||
|
|
|
||
|
|
if ( ! empty( $card['lines'] ) && is_array( $card['lines'] ) ) {
|
||
|
|
echo '<dl>';
|
||
|
|
foreach ( $card['lines'] as $label => $value ) {
|
||
|
|
echo '<dt>' . esc_html( $label ) . '</dt><dd>' . esc_html( $value ) . '</dd>';
|
||
|
|
}
|
||
|
|
echo '</dl>';
|
||
|
|
}
|
||
|
|
|
||
|
|
echo '</div>';
|
||
|
|
|
||
|
|
if ( ! empty( $card['url'] ) ) {
|
||
|
|
printf(
|
||
|
|
'<footer><a class="button" href="%s">%s</a></footer>',
|
||
|
|
esc_url( $card['url'] ),
|
||
|
|
esc_html( isset( $card['action'] ) ? $card['action'] : 'Open' )
|
||
|
|
);
|
||
|
|
}
|
||
|
|
|
||
|
|
echo '</section>';
|
||
|
|
}
|
||
|
|
|
||
|
|
echo '</div></div>';
|
||
|
|
}
|
||
|
|
}
|