The Exec-PHP plugin executes <?php ?> code in your posts, pages and text widgets.
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.
<?php ?> tags after saving the article?eval() error when executing my code?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.
<?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.
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.
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.
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.
The RunPHP plugin by James Van Lommel creates parsing errors with most of the test code below.
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.
The EzStatic 3 plugin by Owen Winkler does not execute test #16 (see below).
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.
You need the following software to be installed on your webserver in order to run the Exec-PHP plugin:
If you have ever installed a WordPress plugin, then installation will be pretty easy:
exec-php directory into /wp-content/plugins/Finished. The rest is self-explanatory. ;-)
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.
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.
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 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.
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.
At the moment the english and german translation ships with the Exec-PHP archive. Further translations for the current version are available for:
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:
exec-php/docs/readme-<locale>.htmlexec-php/docs/screenshot-1-<locale>.png (optional)exec-php/docs/screenshot-2-<locale>.png (optional)exec-php/docs/screenshot-3-<locale>.png (optional)exec-php/languages/exec-php-<locale>.moexec-php/languages/exec-php-<locale>.po (optional)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.
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:
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.
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.
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.
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.
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'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.
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.
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.
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.
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.
The following matrix shows which settings need to be applied to perform specific tasks with the plugin:
| Task | Disable tag balancing | Disable WYSIWYG editor | Assign 'exec_php' cap | Assign 'unfiltered_html' cap | Assign 'switch_themes' cap |
|---|---|---|---|---|---|
| Write/edit PHP code in content of articles | X | X | 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 | X | X | |||
| 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.
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.
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.
Currently there are no known incompatibilities to other plugins or themes.
Besides of limitations with the WYSIWYG editor mentioned above, there currently are no known issues.
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.
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.
| # | Code | Output |
|---|---|---|
| 1 | | |
| 2 | | 1"; ?> |
| 3 | | 1'; ?> |
| 4 | | 2"; ?> |
| 5 | | 2'; ?> |
| 6 | | |
| 7 | | 3";?> |
| 8 | | 3';?> |
| 9 | | 4";?> |
| 10 | | 4';?> |
| 11 | | 1";?> |
| 12 | | 1';?> |
| 13 | | 2";?> |
| 14 | | 3';?> |
| 15 | |
|
| 16 | |
Handle THIS! Handle THAT! |
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.
<?php ?> tags after saving the article?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.
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 <, > to > and & to &. You can do this conversion in a semi automated fashion by using the WP-Simplecode plugin.
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.
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.
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.
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;
?>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.
[?php ?] and < ?php ?>, because regex was buggy and to tough to support[?php ?]<?php ?> tags inside your articles to execute the code inside of itAt the moment it is not planned to include any further features into the plugin but you can add a comment to request further features.