DebugMessages

Summary: A function dmsg() for use in debugging PmWiki recipes

Version: 2024-01-14

Prerequisites: PmWiki 2.3.29; PHP 8

Status: In use

Maintainer: simon

Licence: GPL3 ^#

File: debugmessages-2024-01-14.php Δ

Categories: Markup PmWiki Developer

Users: (view ? / edit)

Discussion: DebugMessages-Talk ?

Questions answered by this recipe

When I am writing a PmWiki recipe how can I quickly and easily display user friendly debug information from the recipe?

Description

This recipe provides a simple function dmsg() that goes to some effort to dump variables passed to it to the PmWiki built in $MessagesFmt array. These can then be displayed using the built in (:messages:) page directive, or better still with the drop in Cookbook:Messages Replacement recipe.

The recipe provides a function function dmsg (string $smsgprefix, $smsgdata, bool $smshtml = false, string $dmsgId = '') {} whose parameters are

$smsgprefix: the prefix to the debug output line or block

$smsgdata: the data, of any type, to be dumped in human friendly format

$smshtml: optional boolean value for when $smsgdata contains preformatted HTML to be passed through

$dmsgId: optional string value

This recipe is inspired by the code snippet in Cookbook:Debugging For Cookbook Authors, and provides an enhanced, tried and tested, reusable version of this.

Installation

download debugmessages-2024-01-14.phpΔ
copy to the /cookbook/ directory as debugmessages.php
add to config.php before any recipe that uses it:
include_once($FarmD/cookbook/debugmessages.php);

Usage

The recipe provides a page variable {$dmsgVersion} which contains the current recipe version, and page variable {$DebugMessages} for a (:if enabled DebugMessages:) recipe installation check.

Configuration

In the recipe that is using dmsg() include the code

if (!function_exists('dmsg')) {
    function dmsg (string $smsgprefix, $smsgdata) { # local instance
        global $MessagesFmt;
        $MessagesFmt['functionName'] [] = $smsgprefix . ': ' . \PHSC (strval($smsgdata));    
    }
}

replacing "functionName" with a unique identifier of your choosing.

This will ensure that whether or not the dmsg() function is available globally the recipe will work and be able to call dmsg().

The recipe will use the parameter $dmsgId as the unique identifier if it is supplied. If $dmsgId is not supplied the recipe will general an identifier based on the calling function, or if the calling funtion is include_once() it will use the basename of the recipe's filename.

dmsg() returns the value of the string added to $MessagesFmt.

Change log / Release notes

2024-01-14 Initial version

On PmWiki

From the PmWiki developer category:

Complex Recipes Guidelines for people who want to share complex cookbook recipes with other PmWiki user
Module Guidelines Guidelines for creating, distributing, and maintaining a recipe for the Cookbook.
Debugging For Cookbook Authors Share tips and tricks with other authors about PmWiki specific debugging
Messages Replacement A drop in replacement for the PmWiki (:messages:) directive
Simple Recipe Template A Simple Recipe Template to provide a framework for PmWiki recipes

Contributors

Special thanks to Petko and the PmWiki documenters.

Talkback

See discussion at DebugMessages-Talk ?

User notes ? : 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.