Компонент VarDumper (сброс переменной)

Компонент VarDumper предоставляет механизмы для извлечения состояния из любой переменной PHP. Так как он надстраивается, он предоставляет улучшенную функцию dump(), которую вы можете использовать вместо var_dump.

Установка

1
$ composer require symfony/var-dumper --dev

Alternatively, you can clone the https://github.com/symfony/var-dumper repository.

Note

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

Note

Если вы используете его внутри приложения Symfony, убедитесь, что был установлен DebugBundle (или запустите composer require symfony/debug-bundle, чтобы установить его).

Функция dump()

Компонент VarDumper создаёт глобальную функцию dump(), которую вы можете использовать вместо, например. var_dump. Используя её, вы получаете:

  • Специализированный просмотр по объектам и источникам, чтобы, к примеру, отфильтровать внутренние объекты Doctrine при сбросе одной сущности прокси, или получить больше информации об открытых с помощью stream_get_meta_data файлах;
  • Конфигурируемые форматы вывода: вывод HTML или цветной командной строки;
  • Возможность сбрасывать внутренние ссылки, мягкие (объекты или источники) или жёсткие (=& в свойствах массивов или объектов). Повторяемое появление одного и того же объекта/масива/истоничка не будут больше появляться снова и снова. Более того, вы сможете исследовать структуру ссылок ваших данных;
  • Возможность оперировать в контексте обработчика буферизации вывода.

Например:

1
2
3
4
5
6
7
8
9
require __DIR__.'/vendor/autoload.php';

// создать переменную, которая может быть чем угодно!
$someVar = ...;

dump($someVar);

// dump() возвращает переданное значение, чтобы вы могли сбросить объект и продолжать использовать его
dump($someObject)->someMethod();

По умолчанию, формат вывода и направление выбираются исходя из вашего текущего PHP SAPI:

  • В командной строке (CLI SAPI), вывод пишется в STDOUT. Это может быть удивительно для некоторых, так как это обходит механизм буферизации вывода PHP;
  • В других SAPI, сбросы пишутся в виде HTML в обычном выводе.

Note

Если вы хотите поймать вывод сброса в виде строки, пожалуйста, прочтите продвинутую документацию, которая содержит такие примеры. Вы также узнаете, как изменять формат или перенаправлять вывод туда, куда вам нужно.

Tip

Для того, чтобы функция dump() всегда была доступна при выполнении любого PHP кода, вы можете установить её на вашем компьютере глобально:

  1. Запустите composer global require symfony/var-dumper;
  2. Добавьте auto_prepend_file = ${HOME}/.composer/vendor/autoload.php к вашему файлу php.ini;
  3. Иногда запускайте composer global update symfony/var-dumper, чтобы иметь последние исправления багов.

Tip

Компонент VarDumper также предоставляет функцию dd() ("dump and die" - "сбрось и умри"). Эта функция отображает переменные используя dump() и сразу прекращает исполнение скрипта (используя функцию PHP exit).

New in version 4.1: Метод dd() появился в Symfony 4.1.

Сервер дампов

New in version 4.1: Сервер дампов появился в Symfony 4.1.

Функция dump() выводит своё содержимое в то же окно браузера или консольный терминал, что и ваше приложение. Иногда смешение настоящего вывода с выводом отладочной информации может запутывать. Поэтому этот компонент предоставляет сервер для сбора всей отладочной информации.

Запустите сервер командой server:dump и когда вы будете вызывать dump(), отладочная информация не будет отображаться в потоке вывода, а отправится на этот сервер, который будет отображать это в своей конслоли или HTML-файле:

1
2
3
4
5
6
# отображает отладочную информацию в консоли:
$ ./bin/console server:dump
  [OK] Server listening on tcp://0.0.0.0:9912

# сохраняет отладочную информацию в файле используя формат HTML:
$ ./bin/console server:dump --format=html > dump.html

Внути приложения Symfony, вывод дамп-сервера настраивается с помощью настройки dump_destination пакета debug.

Интеграция DebugBundle и Twig

DebugBundle позволяет большую интеграцию компонента в приложения Symfony.

Так как генрировние вывода (даже отладки) в контроллере или модели вашего приложения может просто его сломать (например, отправка HTTP заголовков или нарушение вашего просмотра), пакет конфигурирует функцию dump(), чтобы переменные сбрасывались в панели инструментов веб-отладки.

Но если панель инструментов нельзя отобразить так как вы, к примеру, вызвали die()/exit()/dd() или возникла фатальная ошибка, тогда дампы пишутся в обычном потоке вывода.

В шаблоне Twig доступны две конструкции для сброса переменной. Выбор между двумя в основном зависит от ваших личных предпочтейни, и всё же:

  • {% dump foo.bar %} стоит использовать, когда исходный вывод шаблона не стоит изменять: переменные сбрасываются не встроено, а в панели инструментов веб отладки;
  • и наоборот, {{ dump(foo.bar) }} сбрастывает встроено и поэтому может подходить или не подходить в вашем случае (например, не стоит использовать его в атрибуте HTML или теге <script>).

Это поведение можно изменить, сконфигурировав опцию debug.dump_destination. Прочтите больше об этом и других опциях в справочнике конфигурации DebugBundle.

Tip

Если сброшенное содержание сложное, рассмотрите использование локальное поле поиска, чтобы найти определённые переменные или значения. Для начала, нажмите где угодно в сброшенном содержании, а потом нажмите Ctrl. + F или Cmd. + F, чтобы появилось локальное поле поиска. Все общие сокращения для поиска результата поддерживаются (Ctrl. + G или Cmd. + G, F3, и др.) Когда закончите, нажмите Esc., чтобы спрятать поле.

Использование компонента VarDumper в вашем наборе тестов PHPUnit

Компонент VarDumper предоставляет a trait, который может помочь написать некоторые из ваших тестов для PHPUnit.

Это предоставит вам два новых утверждения:

assertDumpEquals()
верифицирует, чтобы сброс переменной, данный в виде второго аргументы, соответствовал ожидаемому сбросу, предоставленному в качестве первого аргумента.
assertDumpMatchesFormat()
такой же, как и предыдущий метод, но принимает заполнители в ожидаемом сбросе, основанном на методе assertStringMatchesFormat(), предоставленном PHPUnit.

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    use \Symfony\Component\VarDumper\Test\VarDumperTestTrait;

    public function testWithDumpEquals()
    {
        $testedVar = array(123, 'foo');

        $expectedDump = <<<EOTXT
array:2 [
  0 => 123
  1 => "foo"
]
EOTXT;

        $this->assertDumpEquals($expectedDump, $testedVar);
    }
}

        // если первый аругмент - строка, он должен быть всем ожидаемым сбросом
        $this->assertDumpEquals($expectedDump, $testedVar);

        // если первый аргумент - не строка, assertDumpEquals() сбрасывает его,
        // и сопоставляет со сбросом второго аргумента
        $this->assertDumpEquals($testedVar, $testedVar);
    }
}

New in version 4.1: Возможность передачи нестроковых переменных в качестве первого аргумента assertDumpEquals() была представлена в Symfony 4.1.

Примеры сброса и вывод

Для простых переменных, чтение вывода должно быть прямолинейным. Вот некоторые примеры, отображающие первую переменную, определённую в PHP, а потом его представление сброса:

1
2
3
4
5
6
7
8
$var = array(
    'a simple string' => "in an array of 5 elements",
    'a float' => 1.0,
    'an integer' => 1,
    'a boolean' => true,
    'an empty array' => array(),
);
dump($var);
../_images/01-simple.png

Note

Серая стрелка - это кнопка переключателя для показа / скрытия детей встроенных структур.

1
2
3
4
5
6
7
$var = "Это многострочная строка.\n";
$var .= "Наведение на строку показывает её длину.\n";
$var .= "Длина UTF-8 строк считается в рамках символов UTF-8.\n";
$var .= "Длина не-UTF-8 строк считается октетами.\n";
$var .= "Из-за этого `\xE9` октет (\\xE9),\n";
$var .= "Эта строка не UTF-8 валидна,  поэтому `b` prefix.\n";
dump($var);
../_images/02-multi-line-str.png
1
2
3
4
5
6
7
8
9
class PropertyExample
{
    public $publicProperty = 'The `+` prefix denotes public properties,';
    protected $protectedProperty = '`#` protected ones and `-` private ones.';
    private $privateProperty = 'Hovering a property shows a reminder.';
}

$var = new PropertyExample();
dump($var);
../_images/03-object.png

Note

#14 это внутренний объект для обработки. Он позволяет сранвивать два последовательных сброса одного и того же объекта.

1
2
3
4
5
6
7
8
class DynamicPropertyExample
{
    public $declaredProperty = 'Это свойство объявлено в определении класса';
}

$var = new DynamicPropertyExample();
$var->undeclaredProperty = 'Runtime added dynamic properties have `"` around their name.';
dump($var);
../_images/04-dynamic-property.png
1
2
3
4
5
6
7
class ReferenceExample
{
    public $info = "Цикличные и родственные ссылки отображаются, как `#number`.\n Наведение на них выделяет все экземпляры в одном сбросе.\n";
}
$var = new ReferenceExample();
$var->aCircularReference = $var;
dump($var);
../_images/05-soft-ref.png
1
2
3
4
5
6
7
8
$var = new \ErrorException(
    "Для некоторых объектов свойства имеют специальные значения,\n"
    ."которые лучше всего отображаются в виде ограничений, вроде\n"
    ."`severity` ниже. Наведение на них отображает значение (`2`).\n",
    0,
    E_WARNING
);
dump($var);
../_images/06-constants.png
1
2
3
4
5
6
7
8
$var = array();
$var[0] = 1;
$var[1] =& $var[0];
$var[1] += 1;
$var[2] = array("Hard references (circular or sibling)");
$var[3] =& $var[2];
$var[3][] = "are dumped using `&number` prefixes.";
dump($var);
../_images/07-hard-ref.png
1
2
3
4
5
$var = new \ArrayObject();
$var[] = "Некоторые источники и специальные объекты, как текущий";
$var[] = "иногда лучше всего представить, используя виртуальные";
$var[] = "свойства, описывающие их внутреннее сстояние.";
dump($var);
../_images/08-virtual-property.png
1
2
3
4
5
6
7
8
$var = new AcmeController(
    "Когда сброс превышает максимальный лимит объектов,\n"
    ."или когда встречаются специальные объекты,\n"
    ."дети могут быть заменены эллипсами и\n"
    ."опционально иметь число, которое сообщает как\n"
    ."и сколько было удалено; В этом случае `9`.\n"
);
dump($var);
../_images/09-cut.png

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.