ExtensionHub

Summary: Configuration panel for extensions
Version: 2024-04-20a
Prerequisites: PmWiki 2.3.31+, PHP 7.0+
Status: Experimental
Maintainer: Petko
License: GPL
Users: +1 (view / edit)
Discussion: ExtensionHub-Talk

Configuration panel for PmWiki extensions (recipes/modules).

This page is a work in progress. Having a few very busy weeks, I'll work on this as time permits. I'll send a message to pmwiki-users when ready. --Petko

Description

Introducing a new family of PmWiki recipes that are easy to install, configure, and maintain.

Extensions

Easy installation:

  • Extensions are placed in the pmwiki/extensions directory.
  • They can be uncompressed, or even left as zip-compressed archives.
  • They can be checked out or pulled from public version control repository, for easy updates.

Easy configuration:

  • There is no need to edit config.php and other local files.
  • The Hub (SiteAdmin.ExtensionHub) lists all available extensions and allows to enable and configure them.
  • The wiki administrator can enable, disable, and edit extension configurations.
  • Extensions can have different configurations for different page name patterns. This is more flexible than the local/Group.php and local/Group.Page.php customizations.

Helper functions for extension authors (see ExtensionDesign):

  • Easier installation for your recipes, with no required editing of config files, and simpler documentation.
  • Adding, removing, enabling, disabling configurations is managed by the Hub.
  • Extensions can define actions when they need to be included, and priority compared to the processing of local.php, stdconfig.php, and relatively to other extensions.
  • Extensions can have custom configuration forms so that wiki admins set their preferences. The forms can be annotated as needed, and can have documentation or demonstrations.
  • The Hub is managing the storage of the configuration values for the extension.
  • Extensions receive their own configuration options for the currently browsed page.
  • Extensions can optionally include scripts, styles, and wiki pages (documentation, templates, forms...).
    • The extension's base directory is similar to that of a PmWiki skin, with a PHP script, optionally CSS/JS files, pictures, fonts, all in one place. This is easier to manage and update compared to older complex recipes that typically have files and directories intermingled in cookbook/ and pub/.
  • There are helper functions to easily inject scripts and styles (shipped with the extension, or external), and wikilib.d pages.
  • There will be a simple way to define i18n strings for different languages, if the recipe needs this (to do).

Hub

The SiteAdmin.ExtensionHub is a configuration panel for extensions. It shows a table with all available extensions, and allows to enable/disable and configure these.

The Hub manages configuration settings for each extension, enables or disables the extension based on the page patterns defined by the wiki admin, and with the priority/actions defined by the developer.

Installation and updates (Hub)

This requires:

  • PmWiki version 2.3.31 or more recent.
  • PHP 7.0 or more recent on the server.

On a wiki farm, you only install the Hub and all extensions once. You can enable the Hub from farmconfig.php, but individual extensions are enabled and configured per field.

Manually

Install:
  1. Unzip extensions-2024-04-20a.zip then rename the directory to just "extensions".
  2. Place the directory "extensions" on your server in your $FarmD directory (as a sibling to the "scripts" directory, in the same directory where pmwiki.php is located).
  3. In config.php or farmconfig.php, add the following line near the top of the file:
    include_once("$FarmD/extensions/hub.php");
    This line should be added after including scripts/xlpage-utf-8.php, but before including scripts/authuser.php (if you include it).

Update an existing Hub installation:

  1. Review the Release notes for changes.
  2. Get the archive extensions-2024-04-20a.zip.
  3. On the wiki, replace the file pmwiki/extensions/hub.php with the one from the archive.

From the GitHub repo

Install:
  1. In your pmwiki directory, clone the repo:
    git clone https://github.com/5ko/extensions.git
  2. In config.php or farmconfig.php, add the following line near the top of the file:
    include_once("$FarmD/extensions/hub.php");
    This line should be added after including scripts/xlpage-utf-8.php, but before including scripts/authuser.php (if you include it).

Update an existing installation:

  1. Review the Release notes for changes.
  2. From inside your pmwiki/extensions directory, call:
    git pull

Configuration (Hub)

If you have a farm, you need to correctly configure $FarmPubDirUrl (you probably already have).

If for some reason the Hub cannot correctly detect your public extensions path, you can set to config.php such a line:

$ExtPubDirUrl = 'https://www.example.com/extensions';

This is the public browser-reachable path to the /extensions directory.

Internationalization

The following strings can be translated in an XLPage:

To do.

Usage (Extension configuration)

PmWiki extensions are recipes with a specific structure, designed to work with the Hub. You can find compatible extensions at Cookbook:Extensions.

There are 3 ways to install an extension:

  1. Check out or pull the code from version control, e.g. a GitHub repository. Do this inside the pmwiki/extensions directory on the server. This method also allows for easy upgrades.
  2. Download a compressed (zip) archive with the extension, provided by the developer, and place it in the pmwiki/extensions directory on the server. In some cases you don't need to uncompress the extension, see below.
  3. Extract (unzip) the compressed extension in the pmwiki/extensions directory on the server.
Should you uncompress individual extensions?

Using compressed extensions (as zip archives) has benefits and downsides:

Benefits for compressed extensions:

  • Easier deployment and updates: Installing and upgrading extensions as zip archives simplifies the deployment process. Administrators can download a single file and (re)place it in the pmwiki/extensions directory.
  • Reduced disk space: Compressed extensions occupy less disk space compared to their uncompressed counterparts.
  • Read-only distribution: The files in the compressed extension are read-only and are unlikely to be modified unintentionally, which reduces the risk of accidentally breaking an extension.
  • Version control: Administrators can easily track and manage different versions of extensions without cluttering the filesystem.
  • PHP files inside compressed extensions are only loaded by the Hub and cannot be called directly from a browser, which may prevent unintended access.

Downsides for compressed extensions:

  • Performance overhead: Decompressing the extensions at runtime may introduce a performance overhead, albeit usually negligible, and static files served from extensions are cached by the browsers for a reasonable amount of time. However, if the extensions are large or there are many of them, or if the website has many visitors in a short time, this overhead might become noticeable.
  • Readability and debugging: It can be more challenging to read and debug code directly from compressed archives. Extracting the files might be necessary for troubleshooting purposes.
  • Depending on server configuration, compressed extensions may be downloadable with a browser, if someone guesses the extension URL. The Hub comes with a .htaccess configuration for Apache forbidding this, but it may not work in some cases, or on other servers. You should evaluate how risky is this.

Benefits and downsides of uncompressed extensions:

  • Faster processing, no decompression overhead.
  • PHP and other files in the extension directory may be reachable via the browser (like for PmWiki skins). For scripts and wikiplain.d pages it might enable unintended access. It is recommended PHP files to start with <?php if (!defined('PmWiki')) exit(); to only run if loaded by PmWiki.

Compressed or not, like with skins and classic recipes, you should only install extensions from trusted sources and authors.

If the extension directory has both a compressed and an uncompressed extension with the same name, the uncompressed one will be loaded.

Extensions placed in pmwiki/extensions are available to the wiki administrators, but they need to be enabled before they become operational. This is done in the page SiteAdmin.ExtensionHub on your wiki, without the need to edit PHP files on the server.

Navigate to SiteAdmin.ExtensionHub on your wiki. By default this page, and the related "hub" action are restricted to "admin" users. You should see a table listing all extensions:

List of extensions

To enable and configure a new extension, locate its row, from the drop-down select "New configuration" (it should already be selected) then press "Edit". A new page will open with something like this:

Configure one extension

Select the checkbox "Enable configuration". In the "Page patterns" field type "*" for all pages, or a different glob pattern, for example for selected groups. The configuration will be enabled on pages that match the pattern, and you could have different configurations for different page patterns.

Press "Save" to save the configuration.

Some extensions provide their own annotated configuration fields. In this case, they will appear between the page patterns and the Save button. (You may need to enable the extension before a custom form is visible.) Please consult the extension documentation.

Notes

To do / some day / maybe

To do.

Change log / Release notes

  • 2024-04-20a: Fix paths for Windows (bug reported by HansB). Refactor .htaccess.
  • 2024-04-15a: Fix RecipeCheck incompatibility, reported by Simon.
  • 2024-04-10: Add functions extAddHeaderResource() and extAddFooterResource().
  • 2024-03-02b: Fix for compressed extensions with version suffix.
  • 2024-03-02: Refactor extGetConfig() to merge a default array.
  • 2024-02-24: Add class HubPlainPageStore, function extAddWikiPlainDir(). FmtExtList() to require admin perms.
  • 2024-02-21: Add page SiteAdmin.ExtensionHub. Page patterns suggestions for existing groups. In .htaccess replace "Options -Indexes" with "IndexIgnore *" (more likely to be available on shared hostings).
  • 2024-02-20: Update PageVariables for Hub actions.
  • 2024-02-19: First public release, ready to be tested.

See also

Cookbook /
ExtensionDesign  How to create extensions compatible with ExtensionHub (Experimental)
Extensions  Recipes compatible with ExtensionHub

Contributors

Written and maintained by Petko.

Comments

See discussion at ExtensionHub-Talk

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.