Embedded PHP Plugin

Allow embedded PHP code to be executed on a wiki page. This optional functionality used to be included in DokuWiki up to “Igor”. But starting with DokuWiki “Jack Jackrum” it was removed as the security implications were deemed too severe for the general public. See DokuWiki Changelog.

IMPORTANT SECURITY WARNING: Do not use this plugin in situations where there might be ANY wiki user: • with editing rights • and who is not 100% trustworthy • or who is not competent to know what they are doing when embedding PHP code! Bad embedded PHP code could delete or corrupt anything on your server that PHP has write access to, including but not limited to your wiki! Disclosure of private information and lots of other accidental or deliberate mischief is also possible! USE ON PRIVATE WIKIS ONLY!

DISCLAIMER: The author is not responsible for any misuse of this plugin. USE AT YOUR OWN RISK!

That said, there are legitimate situations where embedding PHP on wiki pages can be quite useful. And if you mitigate the security issues by only allowing trustworthy and competent editors then the only remaining problem might be the possibility to shoot yourself in the foot by accidentally doing something in PHP that causes problems.

Note: Simply installing this plugin will not enable the execution of embedded PHP code. You also need to set the plugin»embeddedphp»embedphpok and plugin»embeddedphp»privatewiki configuration settings to on. (This was done to prevent accidental activation of the plugin just by installing it.) See Configuration and Settings.

This plugin is intended for DokuWiki “Jack Jackrum” or later. Installing on “Igor” or previous versions would make no sense as it duplicates functionality already included in those releases. However it was tested to work with “Igor” where it overrides the built-in <php> and <PHP> tags as well as obsoleting the phpok configuration setting. It may work the same on previous DokuWiki versions.

Install the plugin using the Extension Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually. The local plugin directory must have the same name as the plugin is named, otherwise the plugin wouldn't work properly.

After installing the plugin you need to set the configuration settings plugin»embeddedphp»embedphpok and plugin»embeddedphp»privatewiki to on to fully enable the functionality. THINK ABOUT THE SECURITY IMPLICATIONS BEFORE DOING SO! Leaving them off will only show the embedded PHP source code on the page, not execute it. See Configuration and Settings.

**Here comes some output from PHP:** <php>
echo 'Hello <i>world</i>! ';
echo 'This is running on PHP version: '.hsc(phpversion());
</php>

Note: Since we do not have direct control over the output of the phpversion() function, we sanitize the output using the DokuWiki function hsc() which is a wrapper around htmlspecialchars(). That avoids nasty surprises in the HTML page source. It is good practice to sanitise any output which might potentially cause problems in the generated HTML of the page.

Result (for example):

**Here comes some more output from PHP:** <PHP>
echo 'Hello <i>world</i>!';
for ($i=0; $i<10; $i++) {
    echo '<br>'.$i;
}
</PHP>

Result:

Basic syntax:

• Inline PHP:

  <php>// your PHP code goes here</php>

  Inserts any output from PHP directly into the HTML of the wiki page. The output of the PHP code will be enclosed in a <span class="embeddedphp"> element if non-empty.

• Block PHP:

  <PHP>// your PHP code goes here</PHP>

  Will create a HTML block element (a <div class="embeddedphp"> element) to contain the output of the PHP code if the output is non-empty.

If either plugin»embeddedphp»embedphpok or plugin»embeddedphp»privatewiki are off then the <php> variant will insert a <code> element containing the formatted PHP source code and the <PHP> variant will use a <pre> element to display the source code. See Configuration and Settings.

Make sure your PHP code does not start with <?php or ends with ?>. Also make sure to properly terminate statements with ;.

Multiline PHP code is fine.

Anything printed in PHP using e.g. echo or other methods will be inserted into the page at that point. But PHP that does not print anything is possible as well.

Please be aware that DokuWiki normally tries to cache pages fairly aggressively. If your PHP code needs to run each time the wiki page is opened/reloaded then you may need to disable caching for the page. See Caching for more information. Use this sparingly though because it degrades performance.

Obviously the closing tag (</php> or </PHP>) may not be present anywhere inside the PHP source code including in PHP comments.

Note: If you need PHP to output wiki source code that is interpreted by DokuWiki then consider using the PHP Wikify plugin. Both plugins can be installed at the same time.

Hint: You can use custom CSS to mark any PHP output generated by this plugin by defining styles for .dokuwiki span.embeddedphp {} and .dokuwiki div.embeddedphp {}. That might be helpful for debugging. As an example consider adding this in conf/userstyle.css (see User Styles):

.dokuwiki span.embeddedphp::before,
.dokuwiki span.embeddedphp::after,
.dokuwiki div.embeddedphp::before,
.dokuwiki div.embeddedphp::after {
  color: #88a;
  background-color: #eef;
  font-size: 65%;
}
.dokuwiki span.embeddedphp::before {
  content: '<php>';
}
.dokuwiki span.embeddedphp::after {
  content: '</php>';
}
.dokuwiki div.embeddedphp::before {
  content: '<PHP>';
}
.dokuwiki div.embeddedphp::after {
  content: '</PHP>';
}

• plugin»embeddedphp»embedphpok

  $conf['plugin']['embeddedphp']['embedphpok']

  Set to on (1) to enable the execution of embedded PHP code.
  Defaults to off (0).

• plugin»embeddedphp»privatewiki

  $conf['plugin']['embeddedphp']['privatewiki']

  Set to on (1) to confirm that this is a private wiki where only trusted and competent people can edit wiki pages.
  Defaults to off (0).

Both configuration options must be set to on for embedded PHP to become executable. This is done to make sure that you have really thought about the security implications and have taken steps to minimise the risks.

My thanks to the authors of DokuWiki, the Wrap Plugin, and PHP Wikify for inspiration and source code to help me understand how to make this plugin work.

I'm aware that other plugins may offer very similar functionality. However I had basically finished the development when they became available and I just needed to complete the publishing part which I decided to follow through on for practise as this is my first DokuWiki plugin

• Fixed documentation link (2023-04-08 14:57)
• Initial commit (2023-04-06 14:59)

Please use the Issue tracker to report any bugs or feature requests.

Please include the following information in your bug report:

• Plugin version (release date)
• DokuWiki version
• PHP version
• Server OS and version
• Any other information about your runtime setup that seems relevant to your issue.

Note: Issues pertaining to bugs in the embedded PHP code will not be accepted. You are on your own for those.

• When using the block element <PHP> syntax the resulting HTML is:

  <p>
  <div class="embeddedphp">output generated by the embedded PHP code</div>
  </p>

  Some browsers will interpret this as:

  <p></p>
  <div class="embeddedphp">output generated by the embedded PHP code</div>
  <p></p>

  See Issue #1.

• Maybe add a parameter to the start tag to selectively enable CSS markup for the produced output?
• Maybe add a parameter to the start tag to make the output be parsed by DokuWiki (just like the PHP Wikify plugin currently does). Writing e.g. <php wiki> may be easier to remember than writing <phpwikify>?
• Maybe add a parameter to the start tag to selectively show the PHP source code instead of executing it?

none yet

Please report issues/bugs through the Issue tracker.

If you have proposals for changes, a pull request would be most welcome.