Bluesome

Exec-PHP plugin for WordPress

What does this plugin do?

The Exec-PHP plugin executes <?php ?> code in your posts, pages and text widgets.

Make it quick. Where can I download the plugin?

Download Exec-PHP 4.9 here!

Why is there so much text below?

Because I hate cool plugins that are badly documented. Even the smallest piece of code needs some documentation. The following text is pretty exhaustive. Feel free to skip the sections you are not interested in. If you have a question about the plugin please first make sure you refer to the latest version and the question is not answered on this page or in the comments section of the plugin homepage. Then - and only then - post your question here.

Table of content

  1. Introduction
    1. Motivation
    2. Features
    3. Concepts of Exec-PHP
    4. Difference to similar plugins
      1. Sniplets
      2. RunPHP 0.2.2 (Mark Somerville)
      3. RunPHP 2.1.1 (James Van Lommel)
      4. PHP Exec 1.7
      5. EzStatic 3
      6. Other plugins
  2. Installation
    1. Requirements
    2. Installing the plugin
    3. Upgrade from previous versions
    4. Upgrade from version 2.0 and earlier
    5. Upgrade to version 4.2 and above
    6. Deactivating the plugin
    7. Uninstalling the plugin
    8. Exec-PHP in your language
    9. Translating Exec-PHP
  3. Usage
    1. Executing PHP code
    2. Configuration
    3. Misconfiguration
    4. Basic test
    5. WordPress' XHTML tag balancing
    6. Writing PHP code with the WYSIWYG editor
    7. Allowing PHP code to be written in articles
    8. Allowing PHP code execution in articles
    9. Allowing PHP code in text widgets
    10. Overview of tasks and their required WordPress configuration
    11. A word about security
    12. Security holes
  4. Troubleshooting
    1. Incompatibilities to other plugins or themes
    2. Limitations
    3. Reporting bugs
    4. Tests to assert plugins functionality
    5. FAQ - Frequently asked questions
      1. Why doesn't the Exec-PHP plugin work as described here?
      2. Why does WordPress mess' up my <?php ?> tags after saving the article?
      3. Why does the plugin fail with an eval() error when executing my code?
      4. How can I just print out PHP code and don't execute it?
      5. Why does my newsfeed spits out parsing errors?
      6. Why does my included PHP file causes parsing errors?
      7. Does the plugin works with WordPress MU?
      8. How do you create the plugin homepage?
  5. Past, present and future
    1. New versions
    2. History of older versions
      1. Version 4.9 (2009-01-07)
      2. Version 4.8 (2008-07-05)
      3. Version 4.7 (2008-05-05)
      4. Version 4.6 (2008-04-06)
      5. Version 4.5 (2008-03-24)
      6. Version 4.4 (2008-01-29)
      7. Version 4.3 (2007-12-11)
      8. Version 4.2 (2007-11-03)
      9. Version 4.1 (2007-10-27)
      10. Version 4.0 (2007-10-25)
      11. Version 3.4 (2007-10-08)
      12. Version 3.3 (2007-08-11)
      13. Version 3.2 (2007-02-10)
      14. Version 3.1 (2007-02-09)
      15. Version 3.0 (2006-08-06)
      16. Version 2.0 (2005-12-22)
      17. Version 1.2 (2005-12-04)
      18. Version 1.1 (2005-08-19)
      19. Version 1.0 (2005-08-18)
    3. Roadmap

Introduction

Motivation

When I was in need of a PHP plugin for my WordPress blog back in 2005, there was no plugin available that allowed me to write PHP code the way I was used to. For example some plugins required the PHP code to be encapsulated in XHTML tags like <phpcode> </phpcode>. This differed from the usual way you write PHP code where you only use <?php ?>. Some of the plugins evaluated the code after WordPress applied some filters like texturize. So it also texturized the PHP code and the plugins had to undo the texturize just for the code part. For more complex code this can not be done correctly because of ambiguity and often led into parsing errors even if the code was syntactically correct.

Features

Concepts of Exec-PHP

Technically Exec-PHP executes code inside of arbitrary text by wrapping the whole text into ?> <?php tags and hand it over to the PHP eval() function. This requires that the executable code itself is encapsulated into <?php ?> tags. By that no parsing of your code needs to be done by the plugin itself.

Difference to similar plugins

There are a lot of PHP plugins available all doing slightly different things. The following list was gathered back in the beginning of 2007 and may not be complete and probably outdated because some of the plugins may have been updated, including more features. Therefore the names of the compared plugins are given including the version number.

Sniplets

The Sniplets plugin by John Godley seems to be a good alternative to Exec-PHP. Although it is harder to configure than Exec-PHP, you may gain some improvements in security due to the way the Sniplets plugin is working.

RunPHP 0.2.2 (Mark Somerville)

The RunPHP plugin by Mark Somerville uses XHTML tag syntax to separate code from HTML. It does strange conversions to "fix" texturized posts and does not support WordPress' 2.x roles and capabilites system.

RunPHP 2.1.1 (James Van Lommel)

The RunPHP plugin by James Van Lommel creates parsing errors with most of the test code below.

PHP Exec 1.7

The PHP Exec plugin by Priyadi Iman Nurcahyo uses XHTML tag syntax to separate code from HTML. It does strange conversions to "fix" texturized posts.

EzStatic 3

The EzStatic 3 plugin by Owen Winkler does not execute test #16 (see below).

Other plugins

Nowadays there are a lot of similar plugins around that I am simply to lazy to write some further text to. If Exec-PHPs functionality does miss some feature you are desperatly seeking, you may want to take a look on one of the various WordPress plugin databases or drop a feature request.

Installation

Requirements

You need the following software to be installed on your webserver in order to run the Exec-PHP plugin:

Installing the plugin

If you have ever installed a WordPress plugin, then installation will be pretty easy:

Finished. The rest is self-explanatory. ;-)

Upgrade from previous versions

Usually if not specifically mentioned on this page you can upgrade from a previous version of this plugin by simply uninstalling the plugin and afterwards follow the installation instructions. Note that an upgrade may implicitly migrate settings of an older plugin version. Therefore you will not be able to downgrade back to an older version of the plugin.

Upgrade from version 2.0 and earlier

Because directory layout has changed, you have to remove your old exec-php.php file from your /wp-content/plugins/ directory manually and afterwards follow the installation instructions. If you have used the alternative styled tags [?php ?] or you have used the old PHP tag formats of < ?php ?> (notice the space) or <? ?> you have to migrate all of these into the format of <?php ?>. You can either do this manually or use the Search and Replace plugin. Since version 3.1 an automatic migration isn't supported anymore for certain reasons.

Upgrade to version 4.2 and above

Depending on your previously installed Exec-PHP version, you may receive an Exec-PHP security alert in your admin menu. Read this section to solve this issue.

Deactivating the plugin

Deactivating the plugin will most likely cause your articles and widgets that contain PHP code to display messed up and may display almost all of your PHP code to your readers. Because of that your PHP code shouldn't contain sensible data e.g. passwords.

Uninstalling the plugin

For uninstalling the plugin simply delete the exec-php directory from the /wp-content/plugins/ directory. You even don't need to deactivate the plugin in the WordPress admin menu. Read this topic if you want to know what happens to your written PHP code in this case.

Exec-PHP in your language

At the moment the english and german translation ships with the Exec-PHP archive. Further translations for the current version are available for:

Translating Exec-PHP

If you like to see Exec-PHP in a language not listed above, get the Exec-PHP archive and use a tool like poedit to translate the languages/exec-php.pot file. If you are a really tough, you can also translate this readme.html file aswell. If this is to much work, just translate the readme-generic.html file. Save the readme as readme-<locale>.html and put it all into a Zip archive named exec-php-<locale>.zip. Here <locale> is the shortcut of your language. For the german translation this would be 'de_DE'. The resulting Zip archive would therefore be named exec-php-de_DE.zip. The archive must not contain more than the following files:

Afterwards upload the archive to your site and write a comment at the comments of the plugin homepage and you will be mentioned in the credits.

In case you also provide translation for previous Exec-PHP versions, also link them on your page with the name exec-php-<locale>.<version>.zip. E.g. exec-php.de_DE.4.2.zip for the german translation of Exec-PHP 4.2.

Usage

Executing PHP code

With Exec-PHP you can execute PHP code in the excerpt and the content portion of your posts and pages (in the following called articles) as also as in text widgets. To execute code, just type in the PHP code as you usually would, encapsulated in <?php ?> tags.

Writing code in articles or text widgets may require some further tuning to the blog and user settings. To have the plugin work properly with PHP code in the content of a users article, do as follows:

Configuration

The plugin comes with its own configuration menu that is accessible through 'Settings > Exec-PHP'. The configuration menu is only accessible for users that do have the 'edit_plugins' capability. This is usually only assigned to the Blog Administrator. If you have disabled Javascript or you are running Exec-PHP with WordPress 2.0.x you will not see or only see parts of the plugin configuration menu.

The configuration menu is divided into two parts, the Settings section and the Information section. In the Settings section you can adjust the plugin's behavior to your needs while the Information section shows which users are allowed to execute PHP code.

The Exec-PHP configuration menu

Misconfiguration

If the blog or user settings are not appropriate to write PHP code, you will get a warning on the 'Write' dialog or 'Widgets' menu respectivly.

An Exec-PHP warning in the 'Write' menu

The WYSIWYG Convesion Warning can be turned off through the 'Users > Your Profile' menu. Nevertheless, this is not the recommended way, because this can cause you to accidently render PHP code in articles permanently unuseful.

Exec-PHP warning configuration in the 'Users > Your Profile' menu

If you have disabled Javascript or you are running Exec-PHP with WordPress 2.0.x you will not receive any warnings even if your blog or user settings are not configured appropriately to run Exec-PHP.

Basic test

For validating, that the plugin works properly, log in as Administrator, apply the settings listed above and create a new article and write the following text:

<?php echo "This is the Exec-PHP 'Hello World'"; ?>

This should always work. When displaying the post and everything works fine, you should see:

This is the Exec-PHP 'Hello World'

WordPress' XHTML tag balancing

Depending on your PHP code it may be necessary to turn off WordPress' built in XHTML tag balancing if the code is written in the content of an article. This can be done through the setting 'WordPress should correct invalidly nested XHTML automatically' on the 'Settings > Write' menu in WordPress. If in question, better turn this option off. An alternative to turning this option off may be to install the Mime Type Plugin and use the mime type text/html individually on each article that contains PHP.

Writing PHP code with the WYSIWYG editor

To successfully write PHP code in the content of an article, the WYSIWYG editor needs to be turned off through the 'Users > Your Profile' menu. It is not enough to simply keep the WYSIWYG editor on, switch to the 'Code' tab of the editor in the 'Write' menu and save the article. This will render all contained PHP code permanently unuseful.

Instead of turining off the WYSIWYG editor in your user profile you can temporarily disable it for certain articles by using the Deactivate Visual Editor plugin. I haven't tested it but it sounds like a reasonable solution for you guys that like to use the WYSIWYG editor.

If you still are in need of writing PHP code with the TinyMCE WYSIWYG editor, you may want to experiment with some TinyMCE plugins that may allow to write PHP code. Such experiments are outside of the scope of this plugin. From my point of view there is a general requirements conflict when you are in need of writing PHP code with any kind of WYSIWYG editor. Therefore it is not planned to natively support writing PHP code in the WYSIWYG editor for any upcoming release of the Exec-PHP plugin.

Allowing PHP code to be written in articles

Before executing PHP code, the user needs to write it first. ;-) A user may experience problems in writing PHP code in the content of an article, because in the way that WordPress will rewrite the code (and therefore will break it for later execution) during saving the article. This is because the user also needs the 'unfiltered_html' capability assigned to.

Assigning capabilities to roles or users is out of the scope of this plugin. Because WordPress has no built-in configuration menu in the admin menu to assign roles/capabilities, you need to install one of the available role/capability manager plugins as the one mentioned in the requirements.

Allowing PHP code execution in articles

After installation, execution of PHP code is limited to the Administrator role by default. By assigning the 'exec_php' capability to another role or user will allow them to execute PHP code in their posts.

Assigning capabilities to roles or users is out of the scope of this plugin. Because WordPress has no built-in configuration menu in the admin menu to assign roles/capabilities, you need to install one of the available role/capability manager plugins as the one mentioned in the requirements.

Allowing PHP code in text widgets

By default execution of PHP code in widgets is activated. Any user who has the 'switch_themes' capability can write and execute PHP code in text widgets. Because this may be a security issue, you may want to disable PHP code execution in widgets through the plugin configuration menu.

Overview of tasks and their required WordPress configuration

The following matrix shows which settings need to be applied to perform specific tasks with the plugin:

TaskDisable tag balancingDisable WYSIWYG editorAssign 'exec_php' capAssign 'unfiltered_html' capAssign 'switch_themes' cap
Write/edit PHP code in content of articlesXX X 
Execute PHP code in content of articles  X  
Write/edit PHP code in excerpt of articles   X 
Execute PHP code in excerpt of articles  X  
Write/edit PHP code in widgets   XX
Execute PHP code in widgets    X

To make things clear: If a user wants to write a new article and want to execute PHP code inside of its content, he needs to have both - the 'exec_php' and 'unfiltered_html' - capabilities assigned to. Otherwise the PHP code will get messed up during saving the article and the raw PHP code itself will be displayed instead of executing it.

For writing and executing code in the excerpt of an article, the user only needs the 'unfiltered_html' capability.

If a user wants to write PHP code inside of a text widget, he only needs the 'unfiltered_html' capability. The execution of PHP code inside of widgets is not restricted by any capability. This means that every user of your blog who can write widgets - which is restricted by the 'switch_themes' capability - can execute PHP code.

A word about security

By using this plugin a user can use the full PHP API and WordPress API. There are no restrictions to execute only certain subsets of functionality. Allowing your users to write and execute PHP code will expose your WordPress installation in specific and your server installation in general. By that a user can easily take over your blog, your server or the whole internet (just kidding about the last one). If in doubt, don't allow a user to execute PHP code. This can be easily adjusted on a per user base.

Security holes

Depending on your configuration, you may receive a security alert that will point you to the 'Security hole' Information section of the plugin configuration menu. This is because you have users defined in your blog (typically called Editors), that are allowed to edit others users articles. If the Editor is not allowed to execute PHP code but the user that the Editor is allowed to edit its articles, then the Editor can add malicious PHP code in this users article.

To solve this issue, the Exec-PHP plugin introduces the 'edit_others_php' capability. It is advised to either assign both or none of the 'exec_php' and 'edit_others_php' capability to your editors. You probably want to split the current Editor role into two different Editor roles, one that is allowed to execute and edit other PHP code, and the second that isn't.

Troubleshooting

Incompatibilities to other plugins or themes

Currently there are no known incompatibilities to other plugins or themes.

Limitations

Besides of limitations with the WYSIWYG editor mentioned above, there currently are no known issues.

Reporting bugs

You can post bug reports to the comments. Before doing this make sure your PHP script is running properly in a separate file. If it does, assure that you did not hit the "Globals" issue. If you still think it's a bug in the plugin, during writing of the bug report keep in mind that WordPress' commenting system is not build to write unescaped code. So better convert the code to the correct XHTML entities before commenting here. Alternativly point to your code using an external link or get in contact with me by using the contact form of my author page.

Tests to assert plugins functionality

Following is a list of tests that were made to assert the plugins functionality. On the left side the PHP code taken directly from the tests is written. On the right side the live output generated by the Exec-PHP plugin is shown. If you view this documentation as a static HTML file obviously the PHP code isn't executed and will look messy. Because of the content of this test, this page will not verify as XHTML. If you think, your favorite PHP plugin is better than this one, try out all the tests below and see if this works correctly.

#CodeOutput
1
<?php ?>
2
<?php echo "a?>1"; ?>
1"; ?>
3
<?php echo 'b?>1'; ?>
1'; ?>
4
<?php echo "a?>2"; ?>
2"; ?>
5
<?php echo 'b?>2'; ?>
2'; ?>
6
<?php?>
7
<?php echo"a?>3";?>
3";?>
8
<?php echo'b?>3';?>
3';?>
9
<?php echo"a?>4";?>
4";?>
10
<?php echo'b?>4';?>
4';?>
11
<?php echo "c";?>1";?>
1";?>
12
<?php echo 'd';?>1';?>
1';?>
13
<?php echo "c';?>2";?>
2";?>
14
<?php echo 'd";?>3';?>
3';?>
15
<?php
echo "impressive\n '";
echo 'string\' "';
echo "\n\thandling\"";
?>
16
<?php if (1) { ?>
<b>Handle THIS!</b>
<?php } else { ?>
<i>Handle THAT!</i>
<?php } ?>
Handle THIS! Handle THAT!

FAQ - Frequently asked questions

Why doesn't the Exec-PHP plugin work as described here?

If the plugin does not work as described on this site although you configured your blog and user settings properly then it is very likely that a different plugin is interfering with Exec-PHPs functionality. To boil things down, deactivate all other plugins beside Exec-PHP and see if the malfunction has gone away.

Why does WordPress mess' up my <?php ?> tags after saving the article?

RTFM. Read this.

Why does the plugin fail with an eval() error when executing my code?

If you experience a PHP error message like 'Some error in /home/minime/htdocs/blog/wp-content/plugins/exec-php/includes/runtime.php(42) : eval()’d code on line 666' then it's time to repair your PHP code. If you are unsure where your code breaks, first run it in a separate file to punch out all bugs and afterwards copy the code into your article or widget. To reduce the noise in the comments section of the plugin homepage I will delete all entries refering to this topic.

How can I just print out PHP code and don't execute it?

If you just want to print out code and don't want to execute it, e.g. like it is done here on this page, you have to make sure to convert your code to the correct XHTML representation. To do so you have to escape the following characters: < to &lt;, > to &gt; and & to &amp;. You can do this conversion in a semi automated fashion by using the WP-Simplecode plugin.

Why does my newsfeed spits out parsing errors?

Assume your code is working outside an article. The PHP parser may still spit out error messages in your newsfeed but not if you are viewing your article even if everything seems to be correct. This will happen if you have defined your own functions, classes, etc. For the newsfeeds WordPress will read the content of each article twice (once for the summary and once for the whole article) and so causing the PHP code to be executed twice. For example the following code in your article would work if you view the article on your webpage but would cause your newsfeed to break:

Article:

<?php
function hello()
{
  echo 'Hello World';
}
hello();
?>

As a general rule I would advise to separate all definitions into a file and reference to it by calling require_once(). So the above example would be split into two parts, your article and a file.

Article:

<?php
require_once(ABSPATH. 'example.php');
hello();
?>

File (here example.php):

<?php
function hello()
{
  echo 'Hello World';
}
?>

Please note that require_once() is using a fully qualified path. This is mandatory because depending on the context of the viewer a relative path would point to different locations e.g. for viewing your main blog page, viewing a single post, viewing the newsfeed, etc.

Why does my included PHP file causes parsing errors?

Assume your included code is working outside an article and the path to the include file is correct. The PHP parser may still spit out error messages even if everything seems to be correct. This can happen when your included file assumes it runs on global scope level and does not use the keyword global to declare its global variables. As example create a new article with the following code:

Article:

<?php require_once(ABSPATH. 'example.php'); ?>

After that copy the following code into a new file named example.php and store it in your webservers root directory:

File (here example.php):

<?php
$g_text = 'Hello World';
function hello()
{
  global $g_text;
  echo $g_text;
}
hello();
?>

Although the file example.php will execute fine if you just access the file directly, this test will end up in unexpected behaviour because assigning a value to the $g_text variable hasn't taken place in global scope in terms of the used WordPress hook to execute your code. This is because of how WordPress works and there is no way to handle this in the plugin. You can work around this problem by adding the following PHP code into your post before the include statement or into the file you want to include at the very beginning:

global $g_text;

No need to say, you have to do this for each global variable where this wasn't already done by the original programmer of the code. Another way would be to contact the original programmer and kindly ask him to change his code.

Does the plugin works with WordPress MU?

WordPress is not WordPress MU. The plugin was written for WordPress but it may probably also work with WordPress MU. If you want to provide a patch to increase compatiblity with WordPress MU, I will be happy to incooperate it in the next official plugin release.

How do you create the plugin homepage?

Glad you've asked. This is a great use case to show you what can be achieved by the Exec-PHP plugin. The plugin homepage is basically a WordPress post running a PHP script thru Exec-PHP that reads and parses the readme.html that comes with the Exec-PHP installation. By that, when I release a new plugin version, I only have to upload the plugin files to the webserver. The documentation will be updated automatically on the plugin homepage. The complete code is:

<?php
// read readme.html depending on locale; plugin translation not yet loaded
global $wp_version;
if (version_compare($wp_version, '2.6.dev') >= 0)
  load_plugin_textdomain(ExecPhp_PLUGIN_ID,
    false, ExecPhp_HOMEDIR. '/languages');
else
  load_plugin_textdomain(ExecPhp_PLUGIN_ID,
    ExecPhp_PLUGINDIR. '/'. ExecPhp_HOMEDIR. '/languages');

$doc_dir = ExecPhp_HOME_URL. '/docs/';
$doc_filename = ExecPhp_HOME_DIR. '/docs/'. __s('readme.html', ExecPhp_PLUGIN_ID);
$content = file_get_contents($doc_filename);

// strip HTML header
$content = preg_replace('/^.*<!\-\-\s*start of content\s*\-\->/is',
  '', $content);

// strip HTML footer depending whether viewing the whole post or only
// the excerpt
$pattern = '/<!\-\-\s*more\s*\-\->.*$/is';
if (is_single())
  $pattern = '/<!\-\-\s*end of content\s*\-\->.*$/is';
$content = preg_replace($pattern, '', $content);

// eval readme.html to generate output of test cases
ob_start();
eval(" ?> $content <?php ");
$content = ob_get_contents();
ob_end_clean();

// adjust relative image links
$content = preg_replace('/<img\s+src\s*=\s*([\'\"])/is',
  '<img src=\1'. $doc_dir, $content);
$content = preg_replace('/<a\s+href\s*=\s*([\'\"])\s*([^\1p]+\.png\s*\1)/isU',
  '<a href=\1'. $doc_dir. '\2', $content);

// done
echo $content;
?>

Past, present and future

New versions

New versions may come out from time to time including new features or bugfixes. You can keep track of the plugins development by manually checking or subscribing to the comments. Since WordPress 2.3 you will also be noticed about plugin upgrades through the 'Plugins' menu in WordPress.

New releases will always justify the code and will cause the version number to be increased. Nevertheless the downloadable archive may change from time to time without having the version number to be increased. This will happen when the plugins documentation will be updated. In this case there will be no announcement on this site, because this may happen rather frequently.

History of older versions

Version 4.9 (2009-01-07)
Version 4.8 (2008-07-05)
Version 4.7 (2008-05-05)
Version 4.6 (2008-04-06)
Version 4.5 (2008-03-24)
Version 4.4 (2008-01-29)
Version 4.3 (2007-12-11)
Version 4.2 (2007-11-03)
Version 4.1 (2007-10-27)
Version 4.0 (2007-10-25)
Version 3.4 (2007-10-08)
Version 3.3 (2007-08-11)
Version 3.2 (2007-02-10)
Version 3.1 (2007-02-09)
Version 3.0 (2006-08-06)
Version 2.0 (2005-12-22)
Version 1.2 (2005-12-04)
Version 1.1 (2005-08-19)
Version 1.0 (2005-08-18)

Roadmap

At the moment it is not planned to include any further features into the plugin but you can add a comment to request further features.