Issue #1367000 by chris.leversuch, oriol_e9g, David_Rothstein: Clean up API docs...
[project/drupal.git] / modules / php / php.module
CommitLineData
ffe4dc84 1<?php
ffe4dc84
DB
2
3/**
4 * @file
5 * Additional filter for PHP input.
6 */
7
ffe4dc84 8/**
1da26fad 9 * Implements hook_help().
ffe4dc84 10 */
9e6ef53c
H
11function php_help($path, $arg) {
12 switch ($path) {
ffe4dc84 13 case 'admin/help#php':
7d4f8c7a
AB
14 $output = '';
15 $output .= '<h3>' . t('About') . '</h3>';
6d0ca97b 16 $output .= '<p>' . t('The PHP filter module adds a PHP filter to your site, for use with <a href="@filter">text formats</a>. This filter adds the ability to execute PHP code in any text field that uses a text format (such as the body of a content item or the text of a comment). <a href="@php-net">PHP</a> is a general-purpose scripting language widely-used for web development, and is the language with which Drupal has been developed. For more information, see the online handbook entry for the <a href="@php">PHP filter module</a>.', array('@filter' => url('admin/help/filter'), '@php-net' => 'http://www.php.net', '@php' => 'http://drupal.org/handbook/modules/php/')) . '</p>';
7d4f8c7a
AB
17 $output .= '<h3>' . t('Uses') . '</h3>';
18 $output .= '<dl>';
19 $output .= '<dt>' . t('Enabling execution of PHP in text fields') . '</dt>';
20 $output .= '<dd>' . t('The PHP filter module allows users with the proper permissions to include custom PHP code that will get executed when pages of your site are processed. While this is a powerful and flexible feature if used by a trusted user with PHP experience, it is a significant and dangerous security risk in the hands of a malicious or inexperienced user. Even a trusted user may accidentally compromise the site by entering malformed or incorrect PHP code. Only the most trusted users should be granted permission to use the PHP filter, and all PHP code added through the PHP filter should be carefully examined before use. <a href="@php-snippets">Example PHP snippets</a> can be found on Drupal.org.', array('@php-snippets' => url('http://drupal.org/handbook/customization/php-snippets'))) . '</dd>';
21 $output .= '</dl>';
9d551664 22 return $output;
ffe4dc84
DB
23 }
24}
25
26/**
1da26fad 27 * Implements hook_permission().
0f08d97b 28 */
e4a4b7cc 29function php_permission() {
0f08d97b
AB
30 return array(
31 'use PHP for settings' => array(
32 'title' => t('Use PHP for settings'),
25feb96f 33 'restrict access' => TRUE,
0f08d97b
AB
34 ),
35 );
36}
37
38/**
4303ae6e 39 * Evaluates a string of PHP code.
0f08d97b 40 *
4303ae6e 41 * This is a wrapper around PHP's eval(). It uses output buffering to capture
42 * both returned and printed text. Unlike eval(), we require code to be
43 * surrounded by <?php ?> tags; in other words, we evaluate the code as if it
44 * were a stand-alone PHP file.
0f08d97b
AB
45 *
46 * Using this wrapper also ensures that the PHP code which is evaluated can not
47 * overwrite any variables in the calling code, unlike a regular eval() call.
48 *
4303ae6e 49 * This function is also used as an implementation of
50 * hook_filter_FILTER_process().
51 *
0f08d97b
AB
52 * @param $code
53 * The code to evaluate.
4303ae6e 54 *
0f08d97b 55 * @return
4303ae6e 56 * A string containing the printed output of the code, followed by the
57 * returned output of the code.
67f2c101
DB
58 *
59 * @ingroup php_wrappers
4303ae6e 60 *
61 * @see php_filter_info()
0f08d97b
AB
62 */
63function php_eval($code) {
64 global $theme_path, $theme_info, $conf;
65
66 // Store current theme path.
67 $old_theme_path = $theme_path;
68
69 // Restore theme_path to the theme, as long as php_eval() executes,
70 // so code evaluated will not see the caller module as the current theme.
71 // If theme info is not initialized get the path from theme_default.
72 if (!isset($theme_info)) {
73 $theme_path = drupal_get_path('theme', $conf['theme_default']);
74 }
75 else {
76 $theme_path = dirname($theme_info->filename);
77 }
78
79 ob_start();
80 print eval('?>' . $code);
81 $output = ob_get_contents();
82 ob_end_clean();
83
84 // Recover original theme path.
85 $theme_path = $old_theme_path;
86
87 return $output;
88}
89
90/**
4303ae6e 91 * Implements hook_filter_FILTER_tips().
92 *
93 * @see php_filter_info()
ffe4dc84 94 */
6f41d692 95function _php_filter_tips($filter, $format, $long = FALSE) {
ffe4dc84 96 global $base_url;
2dd0b6ff
DB
97 if ($long) {
98 $output = '<h4>' . t('Using custom PHP code') . '</h4>';
99 $output .= '<p>' . t('Custom PHP code may be embedded in some types of site content, including posts and blocks. While embedding PHP code inside a post or block is a powerful and flexible feature when used by a trusted user with PHP experience, it is a significant and dangerous security risk when used improperly. Even a small mistake when posting PHP code may accidentally compromise your site.') . '</p>';
100 $output .= '<p>' . t('If you are unfamiliar with PHP, SQL, or Drupal, avoid using custom PHP code within posts. Experimenting with PHP may corrupt your database, render your site inoperable, or significantly compromise security.') . '</p>';
101 $output .= '<p>' . t('Notes:') . '</p>';
102 $output .= '<ul><li>' . t('Remember to double-check each line for syntax and logic errors <strong>before</strong> saving.') . '</li>';
103 $output .= '<li>' . t('Statements must be correctly terminated with semicolons.') . '</li>';
104 $output .= '<li>' . t('Global variables used within your PHP code retain their values after your script executes.') . '</li>';
105 $output .= '<li>' . t('<code>register_globals</code> is <strong>turned off</strong>. If you need to use forms, understand and use the functions in <a href="@formapi">the Drupal Form API</a>.', array('@formapi' => url('http://api.drupal.org/api/group/form_api/7'))) . '</li>';
106 $output .= '<li>' . t('Use a <code>print</code> or <code>return</code> statement in your code to output content.') . '</li>';
107 $output .= '<li>' . t('Develop and test your PHP code using a separate test script and sample database before deploying on a production site.') . '</li>';
108 $output .= '<li>' . t('Consider including your custom PHP code within a site-specific module or <code>template.php</code> file rather than embedding it directly into a post or block.') . '</li>';
109 $output .= '<li>' . t('Be aware that the ability to embed PHP code within content is provided by the PHP Filter module. If this module is disabled or deleted, then blocks and posts with embedded PHP may display, rather than execute, the PHP code.') . '</li></ul>';
110 $output .= '<p>' . t('A basic example: <em>Creating a "Welcome" block that greets visitors with a simple message.</em>') . '</p>';
111 $output .= '<ul><li>' . t('<p>Add a custom block to your site, named "Welcome" . With its text format set to "PHP code" (or another format supporting PHP input), add the following in the Block body:</p>
ffe4dc84 112<pre>
846fa831 113print t(\'Welcome visitor! Thank you for visiting.\');
56d2664a 114</pre>') . '</li>';
2dd0b6ff 115 $output .= '<li>' . t('<p>To display the name of a registered user, use this instead:</p>
ffe4dc84
DB
116<pre>
117global $user;
118if ($user->uid) {
ca8eee75 119 print t(\'Welcome @name! Thank you for visiting.\', array(\'@name\' => format_username($user)));
ffe4dc84
DB
120}
121else {
846fa831 122 print t(\'Welcome visitor! Thank you for visiting.\');
ffe4dc84 123}
56d2664a 124</pre>') . '</li></ul>';
2dd0b6ff
DB
125 $output .= '<p>' . t('<a href="@drupal">Drupal.org</a> offers <a href="@php-snippets">some example PHP snippets</a>, or you can create your own with some PHP experience and knowledge of the Drupal system.', array('@drupal' => url('http://drupal.org'), '@php-snippets' => url('http://drupal.org/handbook/customization/php-snippets'))) . '</p>';
126 return $output;
127 }
128 else {
129 return t('You may post PHP code. You should include &lt;?php ?&gt; tags.');
ffe4dc84
DB
130 }
131}
132
133/**
1da26fad 134 * Implements hook_filter_info().
ffe4dc84 135 *
75983620 136 * Provide PHP code filter. Use with care.
ffe4dc84 137 */
2abbabbc 138function php_filter_info() {
75983620
DB
139 $filters['php_code'] = array(
140 'title' => t('PHP evaluator'),
141 'description' => t('Executes a piece of PHP code. The usage of this filter should be restricted to administrators only!'),
142 'process callback' => 'php_eval',
143 'tips callback' => '_php_filter_tips',
144 'cache' => FALSE,
2abbabbc 145 );
75983620 146 return $filters;
ffe4dc84 147}