{eac}Doojigger: Providing Automatic Updates

{eac}Doojigger derivative plugins and custom extension plugins may provide automatic updating similar to WordPress-hosted plugins.

Document Header

Homepage:https://eacDoojigger.earthasylum.com/ Author:EarthAsylum Consulting Last Updated:31-Aug-2022 Contributors:Kevin Burkholder Requires {eac}Doojigger:1.2.0

Description

Summary

WordPress hosted plugins provide updating functionality automatically. Whenever a new version of a plugin is updated in the WordPress repository, update notifications are seen in your WordPress dashbord on the plugins page.

You can provide the same functionality with your externally or self hosted plugin with a few easy changes.

See Screenshots

Plugin Header

Both derivative plugins and extension plugins must provide the 'Update URI' and 'Version' in the main plugin file header (myAwesomePlugin.php or myAwesomeExtension.php).

As well, other information should be included in the plugin header...

/**
 * Plugin Name:         my plugin/extension name
 * Description:         my plugin/extension description (up to 150 characters)
 * Version:             1.0.0 (major.minor.patch)
 * Requires at least:   5.5.0 (Minimum WordPress version)
 * Tested up to:        6.0 (currently tested WordPress version)
 * Requires PHP:        7.2 (minimum PHP version)
 * Plugin URI:          url to your web page for this plugin/extension
 * Update URI:          url to the JSON file for this plugin/extension
 * Author:              your name
 * Author URI:          your website/profile
 */

See WordPress Plugin Header Requirements

The 'Update URI' must return the JSON Updater Object that provides the required information for WordPress to detect and automate the updating of your plugin.

Derivative Plugin Auto-Updating

Derivative Plugins can auto-update simply by including the aforementioned header values and extending the proper abstract class.

  1. In your main plugin file (myAwesomePlugin.php)
    • add (at least) 'Update URI' and 'Version' to the header.
  2. In your plugin class file (Plugin/myAwesomePlugin.class.php)
    • Your plugin class must extend \EarthAsylumConsulting\abstract_context

myAwesomePlugin.php

/**
 * Plugin Name: My Awesome Plugin
 * Update URI:  https://myawesomeserver.com/myAwesomePlugin.json
 * Version: 1.0.0
 */

myAwesomePlugin.class.php

namespace myAwesomeNamespace\Plugin;

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context
{
    public function __construct(array $header)
    {
        parent::__construct($header);
    }
}

Extension Plugin Auto-Updating

Extension Plugins can auto-update simply by including the aforementioned header values and adding a small amount of code.

  1. In your main plugin file (myAwesomeExtension.php)
    • add 'Update URI' and 'Version' to the header.
  2. In your extension file (myAwesomeExtension.extension.php)
    • use \EarthAsylumConsulting\Traits\plugin_update;
    • set $this->update_plugin_file to the path to your main plugin file (myAwesomeExtension.php)

myAwesomeExtension.php

/**
 * Plugin Name: My Awesome Extensions
 * Update URI:  https://myawesomeserver.com/myAwesomeExtension.json
 * Version: 1.0.0
 */

myAwesomeExtension.extension.php

namespace myAwesomeNamespace\Extensions;

class myAwesomeExtension_extension extends \EarthAsylumConsulting\abstract_extension
{
    use \EarthAsylumConsulting\Traits\plugin_update;

    public function __construct($plugin)
    {
        $this->update_plugin_file = dirname(__DIR__).'/myAwesomeExtension.php';
        parent::__construct($plugin);
    }
}
return new myAwesomeExtension_extension($this);
Top
Screen Shots
  1. Upgrade Notice Upgrade Notice

  2. View Details View Details

Top
JSON Updater Object

The JSON updater object is a simple text file in JSON format that provides the needed information for both the {eac}Doojigger plugin_updater trait and for WordPress.

{
    "plugin":           "plugin-directory/plugin-file-name.php",
    "name":             "plugin title",
    "homepage":         "url to your web page for this plugin/extension",
    "description":      "short description (up to 150 characters)",
    "version":          "1.0.0",
    "last_updated":     "2022-08-31 01:54:36 +00:00",
    "requires":         "5.5.0",
    "tested":           "6.0",
    "requires_php":     "7.2",
    "download_link":    "https://myawesomeplugin.zip",
    "donate_link":      "paypal.me or something",
    "author":           "<a href='https://www.your-website.com'>Your Name</a>",
    "sections":         {
        "description":      "long description/documentation",
        "installation":     "installation instructions",
        "faq":              "frequently asked questions",
        "changelog":        "recent changes":,
        "upgrade_notice":   "notice when upgrading",
        "screenshots":      "see below"
    },
    "contributors":     {"id": {"display_name":"...","profile":"...","avatar":"..."}},
    "banners":          {
        "low":              "url_to_lowres_(772x250)_banner.jpg",
        "high":             "url_to_highres_(1544x500)_banner.jpg"
    },
    "icons":            {
        "low":              "url_to_lowres_icon-128x128.png",
        "high":             "url_to_highres_icon-256x256.png"
    }
}

Requirements

You must include You should include If omitted
plugin name name defaults to the directory of "plugin"
version description requires defaults to 5.5.0
download_link last_updated tested defaults to requires
requires requires_php defaults to 7.2
tested

Sections

Each of the sections elements are optional (you should include at least "description") and may use HTML markup.

Screenshots

screenshots should look something like...

"screenshots":  "<ol>
                <li><p>screen shot title
                <img src='https://www.your-website.com/screenshot-1.png' alt='screen shot title' />
                </p></li>
                </ol>",

Upgrade Notice

If upgrade_notice is present, it will be displayed on the WordPress Plugins and the dashboard Updates screen when an update is available.

The dashboard Updates screen will strip out any html tags.

Contributors

The contributors element is typically used for those who have a wordpress.org account...

"contributors":{
    "your_wp_id":{
        "display_name": "Your Name",
        "profile":      "https://profiles.wordpress.org/your_wp_id/",
        "avatar":       "https://www.gravatar.com/avatar/your_gravitar_id"
    }
},

However, you may populate this with non-wp names and urls or omit "profile" and/or "avatar".

JSON Example

myAwesomePlugin.json

(included in the Extras/AutoUpdate folder distributed with {eac}Doojigger)

{
    "plugin": "myAwesomePlugin/myAwesomePlugin.php",
    "name": "My Awesome Plugin",
    "homepage": "https://myawesomeserver.com/myAwesomePlugin/",
    "description": "My Awesome Plugin is a really awesome plugin.",
    "version": "1.0.1",
    "last_updated": "13-Sep-2022",
    "requires": "5.5.0",
    "tested": "6.0",
    "requires_php": "7.2",
    "download_link": "https://myawesomeserver.com/myAwesomePlugin/myAwesomePlugin.zip",
    "donate_link": "",
    "author": "<a href=\"https://www.myawesomeserver.com\">Me</a>",
    "contributors": {
        "_me_": {
            "display_name": "Me",
            "profile": "https://profiles.wordpress.org/_me_/",
            "avatar": "https://www.gravatar.com/avatar/_mygravitarcode_"
        }
    },
    "sections": {
        "description": "<p><em>My Awesome Plugin</em> is a really awesome plugin.</p>",
        "installation": "<p>Installation of this plugin can be managed from the WordPress Dashboard » Plugins » Add New page by clicking the [Upload Plugin] button, then selecting the myAwesomePlugin.zip file from your computer.</p>",
        "changelog": "<h4>Version 1.0.1 – Sep 13, 2022</h4>\n<ul>\n<li>Critical bug fixes.</li>\n</ul>\n<h4>Version 1.0.0 – Aug 31, 2022</h4>\n<ul>\n<li>Initial public release.</li>\n</ul>",
        "screenshots": "<ol>\n<li>myAwesomePlugin\n<img src=\"https://myawesomeserver.com/myAwesomePlugin/assets/screenshot-1.png\" alt=\"myAwesomePlugin\" /></li>\n</ol>",
        "upgrade_notice": "<p>This version fixes critical bugs. Please update immediately.</p>",
        "other_notes": "<p>myAwesomePlugin is a derivative plugin of and requires installation and registration of <a href=\"https://eacDoojigger.earthasylum.com/\">{eac}Doojigger</a></p>",
        "copyright": "<p>Copyright © 2022, Me</p>"
    },
    "banners": {
        "low": "https://myawesomeserver.com/myAwesomePlugin/assets/banner-772x250.jpg",
        "high": "https://myawesomeserver.com/myAwesomePlugin/assets/banner-1544x500.jpg"
    },
    "icons": {
        "low": "https://myawesomeserver.com/myAwesomePlugin/assets/icon-128x128.png",
        "high": "https://myawesomeserver.com/myAwesomePlugin/assets/icon-256x256.png"
    },
    "rating": 100,
    "num_ratings": 1
}
Top
Readme File

Although not required for a self-hosted plugin, your plugin should include a readme file named readme.txt that follows the WordPress readme file standard. Much of the information in your plugin header and the JSON file is mirrored in your readme.txt file.

A readme.txt file IS required for WordPress-hosted plugins and is critical to proper hosting, installation and updating. See WP Hosted

Top
WP Hosted

If your plugin or extension is to be hosted by WordPress, you obviously don't need a JSON file nor should you set Update URI in the plugin file. But what you do need is a readme.txt file.

And there's one little thing that seems to be lacking in WordPress that can easily be fixed...

When WordPress shows an update available on the Plugins screen, it does not display the Upgrade Notice that you may have included in your readme.txt file. Fixing this is very simple.

Upgrade Notice

One important note: for WordPress to parse the Upgrade Notice section of your readme file, it must be versioned. Meaning that there must be sub-sections with the version number. This is the only section that WordPress will parse out of your file.

 == Upgrade Notice ==

 = 1.0.1 =

 This version fixes critical bugs. Please update immediately.

When WordPress shows an update available for version 1.0.1, it will only parse

This version fixes critical bugs. Please update immediately.

Upgrade Notice

If there is no = 1.0.1 = section, then there is no upgrade notice.

Derivative Plugin Upgrade Notice

Derivative Plugins can provide the upgrade notice simply by extending the proper abstract class (which they should be doing anyway).

  1. In your plugin class file (Plugin/myAwesomePlugin.class.php)
    • Your plugin class must extend \EarthAsylumConsulting\abstract_context_wp

myAwesomePlugin.class.php

namespace myAwesomeNamespace\Plugin;

class myAwesomePlugin extends \EarthAsylumConsulting\abstract_context_wp
{
    public function __construct(array $header)
    {
        parent::__construct($header);
    }
}

abstract_context_wp is intended for WordPress hosted plugins and automatically includes the needed filter to display the Upgrade Notice on the plugins page.

Extension Plugin Upgrade Notice

Extension Plugins can provide the upgrade notice simply by adding 2 lines of code.

  1. In your extension file (myAwesomeExtension.extension.php)
    • use \EarthAsylumConsulting\Traits\plugin_update_notice;
    • set $this->update_plugin_file to the path to your main plugin file (myAwesomeExtension.php)

myAwesomeExtension.extension.php

namespace myAwesomeNamespace\Extensions;

class myAwesomeExtension_extension extends \EarthAsylumConsulting\abstract_extension
{
    use \EarthAsylumConsulting\Traits\plugin_update_notice;

    public function __construct($plugin)
    {
        $this->update_plugin_file = dirname(__DIR__).'/myAwesomeExtension.php';
        parent::__construct($plugin);
    }
}
return new myAwesomeExtension_extension($this);

The plugin_update_notice trait will add the needed filter to display the Upgrade Notice on the plugins page.

Top

    Write a Reply or Comment

    Your email address will not be published.


    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>