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 of the plugin and the question is not answered on this page or in the comments of the plugin homepage. Then - and only then - post your question here.
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 and often led into parsing errors even if the code was syntactically correct.
Exec-PHP is a "no frills" plugin. Since version 3.1 it is simply "install and forget". It does not come with any own config interface. All the configuration you may want to apply to it can be done by third party plugins. Technically Exec-PHP executes code inside of <?php ?>
tags by just wrapping your whole text into ?> <?php
tags and hand it over to the PHP eval()
function. 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 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' 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 may 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.
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 panel. Read this topic if you want to know what happens to your written PHP code in this case.
<?php ... ?>
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.
While writing code in text widgets and the excerpt of articles works right out of the box, writing code in the content of articles may require some further tuning to the blog and user settings. To have the plugin work properly with code in the content of a users article, do as follows:
For validating, that the plugin works properly, log in as Administrator, 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 option 'WordPress should correct invalidly nested XHTML automatically' on the 'Options' menu in WordPress. If in question, better turn this option off.
To successfully write PHP code in the content of an article, the WYSIWYG editor needs to be turned off. 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 page in the admin panel 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 page in the admin panel 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 option menu.
The following matrix shows which settings need to be applied to perform specific tasks with the plugin:
Task | Disable tag balancing | Disable WYSIWYG | 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 internt (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.
Currently there are no known incompatibilities to other plugins or themes.
Besides of limitations with the WYSIWYG rich 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, keep in mind that WordPress' commenting system is not build to write unescaped code, so better convert it to the correct XHTML entities before commenting here, point to the 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 | <?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 |
|
|
16 |
|
Handle THIS! Handle THAT! |
WordPress is not WordPress MU. The plugin was designed for WordPress. If you want to provide a patch to let this work with WordPress MU, I will be happy to incooperate it in the official plugin release.
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(get_settings('home'). '/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.
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(get_settings('home'). '/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.
<?php ?>
tags after saving the post?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 your whole code or at least change your tags from <?php ?>
to <?php ?>
. You can do this conversion in a semi automated fashion by using the WP-Simplecode plugin.
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 ?>
tags inside your articles to execute the code inside of it[?php ?]
[?php ?]
and < ?php ?>
, because regex was buggy and to tough to supportAt the moment it is not planned to include any further features into the plugin but you can add a comment to request further features.