Refactor: use namespacing in JS and persistence (#1)

Author: JasonTheAdams

README.md

@@ -393,3 +393,38 @@ $notice = AdminNotices::show('my_notice', 'This is a notice')
 $notice = AdminNotices::show('my_notice', 'This is a notice')
     ->notDismissible();
 ```
+
+## Resetting dismissed notices
+
+For dismissible notices, when the user dismisses the notice, it is permanently dismissed. If you
+want
+to reset the dismissed notice(s), there are a couple methods available.
+
+### `resetNoticeForUser($notificationId, $userId)`
+
+Reset a specific notification for a user.
+
+Parameters:
+
+1. `string $notificationId` - The unique identifier for the notice
+2. `int $userId` - The user ID to reset the notice for
+
+```php
+use StellarWP\AdminNotices\AdminNotices;
+
+AdminNotices::resetNoticeForUser('my_notice', get_current_user_id());
+```
+
+### `resetAllNoticesForUser($userId)`
+
+Reset all dismissed notices for a user.
+
+Parameters:
+
+1. `int $userId` - The user ID to reset all notices for
+
+```php
+use StellarWP\AdminNotices\AdminNotices;
+
+AdminNotices::resetAllNoticesForUser(get_current_user_id());
+```

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "stellarwp/admin-notices",
-    "version": "1.0.2",
+    "version": "1.1.0",
     "description": "A handy package for easily displaying admin notices in WordPress with simple to complex visibility conditions",
     "minimum-stability": "stable",
     "license": "MIT",

src/Actions/DisplayNoticesInAdmin.php

@@ -8,15 +8,20 @@
 use DateTimeImmutable;
 use DateTimeZone;
 use StellarWP\AdminNotices\AdminNotice;
+use StellarWP\AdminNotices\Traits\HasNamespace;
 
 /**
  * Displays the provided notices in the admin based on the conditions set in the notice.
  *
+ * @since 1.1.0 added namespacing
  * @since 1.0.0
  */
 class DisplayNoticesInAdmin
 {
+    use HasNamespace;
+
     /**
+     * @since 1.1.0 passed the namespace to RenderAdminNotice
      * @since 1.0.0
      */
     public function __invoke(AdminNotice ...$notices)
@@ -27,7 +32,7 @@ public function __invoke(AdminNotice ...$notices)
 
         foreach ($notices as $notice) {
             if ($this->shouldDisplayNotice($notice)) {
-                echo (new RenderAdminNotice($notice))();
+                echo (new RenderAdminNotice($this->namespace))($notice);
             }
         }
     }
@@ -152,11 +157,17 @@ private function passesScreenConditions(AdminNotice $notice): bool
         return false;
     }
 
+    /**
+     * Checks whether the notice has been dismissed by the user.
+     *
+     * @since 1.1.0 added namespacing to the preferences key
+     * @since 1.0.0
+     */
     private function passesDismissedConditions(AdminNotice $notice): bool
     {
         $userPreferences = get_user_meta(get_current_user_id(), 'wp_persisted_preferences', true);
 
-        $key = "stellarwp/admin-notices";
+        $key = "stellarwp/admin-notices/$this->namespace";
         if (!is_array($userPreferences) || empty($userPreferences[$key])) {
             return true;
         }

src/Actions/RenderAdminNotice.php

@@ -6,49 +6,50 @@
 namespace StellarWP\AdminNotices\Actions;
 
 use StellarWP\AdminNotices\AdminNotice;
+use StellarWP\AdminNotices\Traits\HasNamespace;
 
 /**
  * Renders the admin notice based on the configuration of the notice.
  *
+ * @since 1.1.0 refactored to use namespace and notice is passed to the __invoke method
  * @since 1.0.0
  */
 class RenderAdminNotice
 {
+    use HasNamespace;
+
     /**
-     * @var AdminNotice
+     * Renders the admin notice
+     *
+     * @since 1.1.0 added namespacing and notice is passed to the __invoke method
+     * @since 1.0.0
      */
-    private $notice;
-
-    public function __construct(AdminNotice $notice)
-    {
-        $this->notice = $notice;
-    }
-
-    public function __invoke(): string
+    public function __invoke(AdminNotice $notice): string
     {
-        if (!$this->notice->usesWrapper()) {
-            return $this->notice->getRenderedContent();
+        if (!$notice->usesWrapper()) {
+            return $notice->getRenderedContent();
         }
 
         return sprintf(
-            "<div class='%s' data-notice-id='%s'>%s</div>",
-            esc_attr($this->getWrapperClasses()),
-            $this->notice->getId(),
-            $this->notice->getRenderedContent()
+            "<div class='%s' data-stellarwp-$this->namespace-notice-id='%s'>%s</div>",
+            esc_attr($this->getWrapperClasses($notice)),
+            $notice->getId(),
+            $notice->getRenderedContent()
         );
     }
 
     /**
      * Generates the classes for the standard WordPress notice wrapper.
      *
+     * @since 1.1.0 notice is passed instead of accessed as a property
      * @since 1.0.0
      */
-    private function getWrapperClasses(): string
+    private function getWrapperClasses(AdminNotice $notice): string
     {
-        $classes = ['notice', 'notice-' . $this->notice->getUrgency()];
+        $classes = ['notice', 'notice-' . $notice->getUrgency()];
 
-        if ($this->notice->isDismissible()) {
-            $classes[] = 'is-dismissible';
+        if ($notice->isDismissible()) {
+            $classes[] = "is-dismissible";
         }
 
         return implode(' ', $classes);

src/AdminNotices.php

@@ -35,12 +35,13 @@ class AdminNotices
      * Registers a notice to be conditionally displayed in the admin
      *
      * @since 1.0.0
+     * @since 1.1.0 no longer include namespace in AdminNotice id
      *
      * @param string|callable $render
      */
     public static function show(string $notificationId, $render): AdminNotice
     {
-        $notice = new AdminNotice(self::$namespace . '/' . $notificationId, $render);
+        $notice = new AdminNotice($notificationId, $render);
 
         self::getRegistrar()->registerNotice($notice);
 
@@ -59,7 +60,7 @@ public static function show(string $notificationId, $render): AdminNotice
     public static function render(AdminNotice $notice, bool $echo = true): ?string
     {
         ob_start();
-        (new DisplayNoticesInAdmin())($notice);
+        (new DisplayNoticesInAdmin(self::$namespace))($notice);
         $output = ob_get_clean();
 
         if ($echo) {
@@ -108,12 +109,15 @@ public static function removeContainer(): void
      *
      * This should be called at the beginning of the plugin file along with other configuration.
      *
+     * @since 1.1.0 added namespace validation
      * @since 1.0.0
      */
     public static function initialize(string $namespace, string $pluginUrl): void
     {
         if (empty($namespace)) {
             throw new RuntimeException('Namespace must be provided');
+        } elseif (preg_match('/[^a-zA-Z0-9_-]/', $namespace)) {
+            throw new RuntimeException('Namespace must only contain letters, numbers, hyphens, and underscores');
         }
 
         self::$packageUrl = $pluginUrl;
@@ -138,6 +142,7 @@ public static function getNotices(): array
     /**
      * Rests a dismissed notice for a given user so the notice will be shown again
      *
+     * @since 1.1.0 uses namespacing
      * @since 1.0.0
      */
     public static function resetNoticeForUser(string $notificationId, int $userId): void
@@ -146,17 +151,18 @@ public static function resetNoticeForUser(string $notificationId, int $userId):
 
         $preferencesKey = $wpdb->get_blog_prefix() . 'persisted_preferences';
         $preferences = get_user_meta($userId, $preferencesKey, true);
+        $packageKey = 'stellarwp/admin-notices/' . self::$namespace;
 
-        $notificationKey = self::$namespace . '/' . $notificationId;
-        if (isset($preferences['stellarwp/admin-notices'][$notificationKey])) {
-            unset($preferences['stellarwp/admin-notices'][$notificationKey]);
+        if (isset($preferences[$packageKey][$notificationId])) {
+            unset($preferences[$packageKey][$notificationId]);
             update_user_meta($userId, $preferencesKey, $preferences);
         }
     }
 
     /**
      * Resets all dismissed notices for a given user so all notices will be shown again
      *
+     * @since 1.1.0 uses namespacing and simplified the method
      * @since 1.0.0
      */
     public static function resetAllNoticesForUser(int $userId): void
@@ -165,44 +171,52 @@ public static function resetAllNoticesForUser(int $userId): void
 
         $preferencesKey = $wpdb->get_blog_prefix() . 'persisted_preferences';
         $preferences = get_user_meta($userId, $preferencesKey, true);
+        $packageKey = 'stellarwp/admin-notices/' . self::$namespace;
 
-        if (isset($preferences['stellarwp/admin-notices'])) {
-            $preferenceRemoved = false;
-            foreach ($preferences['stellarwp/admin-notices'] as $key => $value) {
-                if (strpos($key, self::$namespace . '/') === 0) {
-                    unset($preferences['stellarwp/admin-notices'][$key]);
-                    $preferenceRemoved = true;
-                }
-            }
-
-            if ($preferenceRemoved) {
-                update_user_meta($userId, $preferencesKey, $preferences);
-            }
+        if (isset($preferences[$packageKey])) {
+            unset($preferences[$packageKey]);
+            update_user_meta($userId, $preferencesKey, $preferences);
         }
     }
 
     /**
      * Hook action to display the notices in the admin
      *
+     * @since 1.1.0 passes the namespace to the display notices class
      * @since 1.0.0
      */
     public static function setUpNotices(): void
     {
-        (new DisplayNoticesInAdmin())(...self::getNotices());
+        (new DisplayNoticesInAdmin(self::$namespace))(...self::getNotices());
     }
 
     /**
      * Hook action to enqueue the scripts needed for dismissing notices
      *
+     * @since 1.1.0 added the namespacing attribute to the script tag
      * @since 1.0.2 use filetime for versioning, which will bust the cache when the library is updated
      * @since 1.0.0
      */
     public static function enqueueScripts(): void
     {
+        $namespace = self::$namespace;
+        $handle = "$namespace-admin-notices";
         $version = filemtime(__DIR__ . '/resources/admin-notices.js');
 
+        add_filter('script_loader_tag', static function ($tag, $tagHandle) use ($handle, $namespace) {
+            if ($handle !== $tagHandle) {
+                return $tag;
+            }
+
+            $tag = str_replace(' src', ' defer src', $tag);
+
+            $replacement = "<script data-stellarwp-namespace='$namespace'";
+
+            return str_replace('<script', $replacement, $tag);
+        }, 10, 2);
+
         wp_enqueue_script(
-            'stellarwp-admin-notices',
+            $handle,
             self::$packageUrl . '/src/resources/admin-notices.js',
             ['jquery', 'wp-data', 'wp-preferences'],
             $version,

src/Traits/HasNamespace.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StellarWP\AdminNotices\Traits;
+
+trait HasNamespace
+{
+    /**
+     * The namespace for the plugin.
+     *
+     * @var string
+     */
+    protected $namespace;
+
+    public function __construct(string $namespace)
+    {
+        $this->namespace = $namespace;
+    }
+}

src/resources/admin-notices.js

@@ -1,13 +1,36 @@
-jQuery(document).ready(function ($) {
-    const {dispatch} = wp.data;
-    const dismissButtons = $('.notice-dismiss');
+(function ($, dispatch, document) {
+    // Set up the package functions using the namespace provided by the script tag.
+    const currentScript = typeof document.currentScript !== 'undefined' ? document.currentScript : document.scripts[document.scripts.length - 1];
+    const namespace = currentScript.getAttribute('data-stellarwp-namespace');
 
-    dismissButtons.on('click', function (event) {
-        const $this = $(this);
-        const container = $this.closest('.notice');
-        const noticeId = container.data('notice-id');
+    if (!namespace) {
+        console.error('The stellarwp/admin-notices library failed to load because the namespace attribute is missing.');
+        return;
+    }
 
-        const now = Math.floor(Date.now() / 1000);
-        dispatch('core/preferences').set('stellarwp/admin-notices', noticeId, now);
+    window.stellarwp = window.stellarwp || {};
+    window.stellarwp.adminNotices = window.stellarwp.adminNotices || {};
+    window.stellarwp.adminNotices[namespace] = {
+        /**
+         * Dismisses a notice with the given ID.
+         *
+         * @since 1.1.0
+         *
+         * @param {string} noticeId
+         */
+        dismissNotice: function (noticeId) {
+            const now = Math.floor(Date.now() / 1000);
+            dispatch('core/preferences').set(`stellarwp/admin-notices/${namespace}`, noticeId, now);
+        },
+    };
+
+    // Begin notice dismissal code
+    const noticeIdAttribute = `data-stellarwp-${namespace}-notice-id`;
+    const $notices = $(`[${noticeIdAttribute}]`);
+
+    $notices.on('click', '.notice-dismiss', function (event) {
+        const noticeId = $(this).closest(`[${noticeIdAttribute}]`).data(`stellarwp-${namespace}-notice-id`);
+
+        window.stellarwp.adminNotices[namespace].dismissNotice(noticeId);
     });
-});
+})(window.jQuery, window.wp.data.dispatch, document);