Экземпляр класса Runkit_Sandbox создает отдельный поток основного процесса с собственным окружением и выделенной областью памяти (стеком). С помощью дополнительных параметров конструктора можно ограничивать функционал интерпретатора в песочнице, создавая таким образом безопасное окружение для выполнения пользовательского кода.

Замечание: Поддержка песочницы (необходима для runkit_lint(), runkit_lint_file(), и класса Runkit_Sandbox) доступна только начиная с версии PHP 5.1.0 или в специально пропатченных версиях PHP 5.0, а также требует потокобезопасной (thread safe) версии PHP. Для более подробной информации смотрите файл README, поставляемый с пакетом runkit.

Constructor

void Runkit_Sandbox::__construct ([ array $options ] )

options ассоциативный массив, содержащий произвольную комбинацию специальных параметров, перечисленных ниже

safe_mode: Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется с директивой safe_mode = off, то эту опцию можно задействовать в песочнице для включения режима safe_mode. Данный параметр не может быть использован для отключения safe_mode, если он включен во внешнем окружении.
safe_mode_gid: Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется с директивой safe_mode_gid = on, то данную опцию можно задействовать для отключения safe_mode_gid в песочнице. Этот параметр нельзя использовать для включения safe_mode_gid, если он выключен во внешнем окружении.
safe_mode_include_dir: Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется c заданной директивой safe_mode_include_dir, то для песочницы может быть указана новая директория, находящаяся внутри заданной. Значение safe_mode_include_dir так же может быть очищено для возврата к начальным настройкам. Если директива safe_mode_include_dir не была настроена для родительского скрипта, подразумевается, что задан корневой раздел. В таком случае для песочницы можно указать любую директорию, при включенном режим safe_mode.
open_basedir: В параметре open_basedir может быть задана любая директория, находящаяся внутри назначенной open_basedir родительского скрипта. Если параметр open_basedir в родительском скрипте не задан, в качестве его значения используется корневой раздел. В таком случае для песочницы можно указать любой каталог.
allow_url_fopen: Подобно safe_mode, этот параметр может быть изменен только в сторону увеличения ограничений. Допускается устанавливать его значение FALSE в случае, если значение в родительском окружении TRUE.
disable_functions: Список отключенных в песочнице функций через запятую. В этот список не надо вносить уже отключенные в родительском скрипте функции, они таковыми и останутся вне зависимости от наличия в списке.
disable_classes: Список отключенных в песочнице классов через запятую. В этот список не надо вносить уже отключенные в родительском скрипте классы, они таковыми и останутся вне зависимости от наличия в списке.
runkit.superglobal: Список суперглобальных переменных для песочницы через запятую. Перечисленные переменные будут дополнять список существующих суперглобальных переменных, встроенных и заданных с помощью runkit.superglobal в родительском окружении.
runkit.internal_override: Параметр runkit.internal_override может быть только отключен для песочницы.

Пример #1 Пример создания безопасной песочницы


<?php
$options = array(
  'safe_mode'=>true,
  'open_basedir'=>'/var/www/users/jdoe/',
  'allow_url_fopen'=>'false',
  'disable_functions'=>'exec,shell_exec,passthru,system',
  'disable_classes'=>'myAppClass');
$sandbox = new Runkit_Sandbox($options);
/* Незащищенные ini-переменные устанавливаются обычным способом */
$sandbox->ini_set('html_errors',true);
?>

Доступ к переменным

Все глобальные переменные внутри песочницы доступны через свойства объекта Runkit_Sandbox. Необходимо учитывать, что из-за особенностей распределения памяти объекты и ресурсы не могут переноситься между родительским процессом и песочницей. Массивы полностью копируются между интерпретаторами и все ссылки внутри массивов удаляются. Это так же означает, что ссылки между интерпретаторами невозможны.

Пример #2 Работа с переменными в песочнице


<?php
$sandbox = new Runkit_Sandbox();

$sandbox->foo = 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo "{$sandbox->bar}\n";
if (isset($sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
?>

Результат выполнения данного примера:

bar
barbaz
bool(false)

Вызов функций PHP

Любая функция, заданная в песочнице, может быть вызвана через метод объекта Runkit_Sandbox. Так же доступны несколько псевдо-функций: eval(), include, include_once, require, require_once, echo, print, die() и exit().

Пример #3 Использование функций песочницы


<?php
$sandbox = new Runkit_Sandbox();

echo $sandbox->str_replace('a','f','abc');
?>

Результат выполнения данного примера:

fbc

Когда функция песочницы вызывается с параметрами, используются значения этих параметров из родительского скрипта. Если необходимо вызвать функцию со значениями из окружения песочницы, следует передавать их как свойства объекта Runkit_Sandbox. Этот механизм проиллюстрирован на следующем примере.

Пример #4 Передача аргументов функциям в песочнице


<?php
$sandbox = new Runkit_Sandbox();

$foo = 'bar';
$sandbox->foo = 'baz';
echo $sandbox->str_replace('a',$foo,'a');
echo $sandbox->str_replace('a',$sandbox->foo,'a');
?>

Результат выполнения данного примера:

bar
baz

Изменение параметров песочницы

По состоянию на версию runkit 0.5, большинство параметров песочницы могут быть изменены "на лету" с помощью синтаксиса интерфейса ArrayAccess. Некоторые параметры, например, active, доступны только для чтения. Остальные, например, output_handler, могут быть получены и записаны как обычный элемент массива. В будущем могут появиться параметры, доступные только для записи. На текущий момент таких не существует.

**Настройки песочницы. Индикаторы статуса**
Настройка	Тип	Назначение	По умолчанию
active	Boolean (только чтение)	`TRUE` если песочница функционирует, `FALSE` если процесс завершен после вызова die() или exit(), или в результате ошибки при выполнении.	`TRUE` (изначально)
output_handler	Callback	Если указана соответствующая callback-функция, весь вывод песочницы перенаправляется в указанную функцию. Обработчики вывода песочницы работают аналогично системным обработчикам вывода.	None
parent_access	Boolean	Параметр управляет доступом к Runkit_Sandbox_Parent из песочницы. Параметр должен быть включен для работы с функционалом, предоставляемым Runkit_Sandbox_Parent.	`FALSE`
parent_read	Boolean	Разрешает чтение переменных родительского окружения	`FALSE`
parent_write	Boolean	Разрешает запись переменных родительского окружения	`FALSE`
parent_eval	Boolean	Разрешает выполнение кода в родительском окружении DANGEROUS	`FALSE`
parent_include	Boolean	Разрешает подключать php файлы в родительском окружении DANGEROUS	`FALSE`
parent_echo	Boolean	Разрешает выводить данные в родительском окружении, в обход output_handler.	`FALSE`
parent_call	Boolean	Разрешает вызов функций в родительском окружении	`FALSE`
parent_die	Boolean	Разрешает завершать родительский скрипт (а значит и себя тоже)	`FALSE`
parent_scope	Integer	Настройка области видимости песочницы для внешнего окружения: 0 == Глобальная область видимости, 1 == область вызова, 2 == область до области вызова, 3 == область до этой области, и т.д.	0 (Global)
parent_scope	String	В случае, когда параметр parent_scope задан строковым значением, он указывает на массив в глобальной области видимости. Если массива не существует - будет создан пустой массив с указанным именем. Если существует переменная с заданным именем, не являющаяся массивом - будет создан массив, содержащий ссылку на существующую переменную.

Вернуться к: runkit