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

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

Установка

Вы можете установить компонент 2 разными способами:

Note

Если вы используете его внутри приложения Symfony, убедитесь, что в вашем файле app/AppKernel.php включен DebugBundle.

Функция dump()

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

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

Например:

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

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

dump($someVar);

По умолчанию, формат вывода и направление выбираются исходя из вашего текущего 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, чтобы иметь последние исправления багов.

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

DebugBundle позволяет большую интеграцию компонента в полный фреймворк Symfony. Он включен по умолчаниб в окружениях dev и test стандартной версии Symfony.

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

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

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

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

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

Tip

New in version 3.3: Локальное поле поиска было представлено в Symfony 3.3.

Если сброшенное содержание сложное, рассмотрите использование локальное поле поиска, чтобы найти определённые переменные или значения. Для начала, нажмите где угодно в сброшенном содержании, а потом нажмите 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
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);
    }
}

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

Для простых переменных, чтение вывода должно быть прямолинейным. Вот некоторые примеры, отображающие первую переменную, определённую в 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.