Recent Changes - Search:
Cookbook /

ComplexRecipes

Summary: Guidelines for people who want to share complex cookbook recipes with other PmWiki user
Category: PmWiki Developer

These are some guidelines for people who want to share complex cookbook recipes with other PmWiki users. (In this context, "complex" means "consisting of multiple parts", not necessarily "complicated"!)

Distribution

  • Choose a good name for your extension. Below, we use "foo"; that's not a good name!
  • Put your extension into a tarball or zip file (or both) if it consists of more than the file foo.php.
  • The tarball or zip file should create a directory with the name of the extension and the version number, like foo-0.1.
  • Include license information (such as a COPYING file).
  • Include a README file, with installation and other instructions.
  • The files in the directory should lay out like this: 
 
 foo-0.1/
     COPYING.foo (license info)
     README.foo (install & other instructions)
     pmwiki/
         cookbook/
             foo.php (single script, loads others if necessary)
             foo/
                bar.php
                baz.php
         pub/
             css/
                [any css]
             foo/
                [any skins, images, etc.]
         wikilib.d/
             Foo.HomePage (documentation in PmWiki format)
             Foo.OtherDocumentation
  • Installation should comprise opening the tarball, copying the files recursively to the PmWiki directory ("cp -r foo-0.1/pmwiki pmwiki"), throwing a include_once('$FarmC/cookbook/foo.php') into the local/config.php file, and that should be it. Have reasonable defaults for any configuration variables.

Coding guidelines

  • In the very first line of any PHP code, write
<?php if (!defined('PmWiki')) exit();
  • if using strict or namespaces these must go first, e.g.
<?php declare(strict_types=1);
namespace Foo; #
if (!defined('PmWiki')) exit();

This makes sure that it will run if and only if it is called from PmWiki. (Without that, users might run your script directly, getting anything from a blank page or a nasty error message to a security exploit. The WWW server actually isn't supposed to be configured to allow that scenario, but perfect configurations are quite rare.)

  • In the first couple of lines of your extension, set the RecipeInfo for your extension so other code can tell that it's loaded, and to enable Site Analyzer and Recipe Check.
$RecipeInfo['Foo']['Version'] = '2022-01-22'
  • Try to follow PmWiki's variable and function naming practices (CamelCase for everything). That makes it easier for everyone.
  • For configuration variables, prefix the variable name with the name of your extension, to avoid clashes. For example, don't use a variable $Count; use $FooCount instead.
  • Use the SDV() function for your config variables. e.g
\SDV($FooDebug, false);

See also