Конфигурация сервера сброса с переменными окружения

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

Сначала, запустите сервер как обычно:

1

$ ./vendor/bin/var-dump-server

Затем, запустите ваш код с переменной окружения VAR_DUMPER_FORMAT=server, сконфигурировав это значение в файле .env вашего приложения . Для консольных команд вы также можете определить эту переменную окружения так:

1

$ VAR_DUMPER_FORMAT=server [your-cli-command]

Cloners

Клонер используется для создания промежуточного представления любой переменной PHP. Его выводом является объект Data, который оборачивает это представление.

Вы можете создать объект Data следующим образом:

1
2
3
4
5
6
7

use Symfony\Component\VarDumper\Cloner\VarCloner;

$cloner = new VarCloner();
$data = $cloner->cloneVar($myVar);
// это часто потом передаётся дамперу
// см. пример сверху этой страницы
// $dumper->dump($data);

Какой бы ни была клонированная структура данных, результирующие объекты Data всегда являются сериализуемыми.

При создании представления клонируемый объект накладывает ограничения, так что можно представить только подмножество клонируемой переменной. Перед вызовом :метода:`Symfony\\Component\VarDumper\\Cloner\\VarCloner::cloneVar`, можно настроить такие ограничения:

setMaxItems()

Конфигурирует максимальное количество элементов, которые будут клонироваться за минимальной глубиной вложенности. Подсчёт элементов ведётся по алгоритму "сначала в ширину", так что элементы нижнего уровня имеют более высокий приоритет, чем глубоко вложенные элементы. Указание -1 снимает ограничение.

setMinDepth()

Конфигурирует минимальную глубину дерева, при которой мы гарантированно клонируем все элементы. После достижения этой глубины клонироваться будут только элементы setMaxItems. Значение по умолчанию равно 1, что соответствует старым версиям Symfony.

setMaxString()

Конфигурирует максимальное количество символов, которые будут клонироваться перед обрезанием длинных строк. Указание -1 снимает ограничение.

Перед сбросом вы можете ещё больше ограничить результирующий объект Data, используя следующие методы:

withMaxDepth()

Ограничивает сбросы в диапазоне глубины.

withMaxItemsPerDepth()

Ограничивает количество элементов на уровень глубины.

withRefHandles()

Удаляет обработки внутренних объектов для более компактного вывода (полезно для тестов).

seek()

Выбирает только вложенные подчасти уже клонированных массивов, объектов или ресурсов.

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

Dumpers

Дампер отвечает за вывод строкового представления переменной PHP, используя в качестве ввода Data. Назначение и форматирование этого вывода зависит от дампера.

Данный компонент поставляется с HtmlDumper для вывода HTML и CliDumper для опционально окрашенного вывода командной строки.

Например, если вы хотите сбросить какую-то $variable, сделайте:

1
2
3
4
5
6
7

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$cloner = new VarCloner();
$dumper = new CliDumper();

$dumper->dump($cloner->cloneVar($variable));

С помощью первого аргумента конструктора вы можете выбрать поток вывода, в котором будет записываться сброс. По умолчанию CliDumper пишет в php://stdout, а
HtmlDumper - в php://output. Но допустим любой PHP поток (источник или URL).

Вместо адресата потока вы также можете передать ему callable, которое будет вызываться многократно для каждой строки, сгенерированной дампером. Это вызываемое может быть сконфигурировано с помощью первого аргумента конструктора дампера, а также с помощью метода setOutput() или второго аргумента метода dump().

Например, чтобы получить сброс в качестве строки в переменной, вы можете сделать:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$cloner = new VarCloner();
$dumper = new CliDumper();
$output = '';

$dumper->dump(
    $cloner->cloneVar($variable),
    function (int $line, int $depth) use (&$output): void {
        // Отрицательная глубина означает "конец сброса"
        if ($depth >= 0) {
            // Добавляет отступ в два пробела к строчке
            $output .= str_repeat('  ', $depth).$line."\n";
        }
    }
);

// $output теперь наполняется представлением сброса $variable

Другой опцией того же самого может быть:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$cloner = new VarCloner();
$dumper = new CliDumper();
$output = fopen('php://memory', 'r+b');

$dumper->dump($cloner->cloneVar($variable), $output);
$output = stream_get_contents($output, -1, 0);

// $output теперь наполняется представлением сброса $variable

1

$output = $dumper->dump($cloner->cloneVar($variable), true);

Дамеры реализуют интерфейс DataDumperInterface, который указывает метод dump(Data $data). Они также обычно реализуют DumperInterface, который освобождает их от повторной реализации логики, необходимой для прохождения внутренней структуры объекта Data.

HtmlDumper использует тёмную тему по умолчанию. Используйте метод setTheme(), чтобы использовать светлую тему:

1
2

// ...
$htmlDumper->setTheme('light');

HtmlDumper ограничивает длину строки и глубину встаривания вывода, чтобы сделать его более читаемым. Эти опции можно переопределить третьим необязательным параметром метода dump(Data $data):

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\VarDumper\Dumper\HtmlDumper;

$output = fopen('php://memory', 'r+b');

$dumper = new HtmlDumper();
$dumper->dump($var, $output, [
    // 1 и 160 являются значениями по умолчанию для этих опций
    'maxDepth' => 1,
    'maxStringLength' => 160,
]);

Формат вывода дампера может быть точно настроен с помощью двух флажков DUMP_STRING_LENGTH и DUMP_LIGHT_ARRAY, которые передаются в виде битовой карты в третьем аргументе конструктора. Они также могут быть установлены через переменные окружения при использовании assertDumpEquals($dump, $data, $filter, $message) во время модульного тестирования.

Аргумент $filter функции assertDumpEquals() может быть использован для передачи битового поля констант Caster::EXCLUDE_* и влияет на ожидаемый вывод, производимый различными кастерами.

Если DUMP_STRING_LENGTH установлена, то длина строки отображается рядом с ее содержанием:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\AbstractDumper;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$varCloner = new VarCloner();
$var = ['test'];

$dumper = new CliDumper();
echo $dumper->dump($varCloner->cloneVar($var), true);

// array:1 [
//   0 => "test"
// ]

$dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH);
echo $dumper->dump($varCloner->cloneVar($var), true);

// (added string length before the string)
// array:1 [
//   0 => (4) "test"
// ]

Если DUMP_LIGHT_ARRAY установлен, тогда массивы сбрасываются в сокращённом формате, схожем с краткой нотацией массивов PHP:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\AbstractDumper;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$varCloner = new VarCloner();
$var = ['test'];

$dumper = new CliDumper();
echo $dumper->dump($varCloner->cloneVar($var), true);

// array:1 [
//   0 => "test"
// ]

$dumper = new CliDumper(null, null, AbstractDumper::DUMP_LIGHT_ARRAY);
echo $dumper->dump($varCloner->cloneVar($var), true);

// (no more array:1 prefix)
// [
//   0 => "test"
// ]

Если вы хотите использовать обе опции, то вы можете скомбинировать их, используя логический оператор OR |:

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\AbstractDumper;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$varCloner = new VarCloner();
$var = ['test'];

$dumper = new CliDumper(null, null, AbstractDumper::DUMP_STRING_LENGTH | AbstractDumper::DUMP_LIGHT_ARRAY);
echo $dumper->dump($varCloner->cloneVar($var), true);

// [
//   0 => (4) "test"
// ]

Casters

Объекты и источники, вложенные в переменную PHP, "приводятся" к массивам в промежуточном представлении Data. Вы можете настроить представление массива для каждого объекта/источника, подключив к этому процессу Caster. Компонент уже включает в себя множество кастеров для базовых классов PHP и других распространённых классов.

Если вы хотите создать свой собственный кастер, вы можете зарегистрировать его перед клонированием PHP-переменной. Кастеры регистрируются либо в конструкторе клонера, либо с помощью метода addCasters():

use SymfonyComponentVarDumperClonerVarCloner;

$myCasters = [...]; $cloner = new VarCloner($myCasters);

// или

$cloner->addCasters($myCasters);

Предоставленный аргумент $myCasters - это массив, который отображает класс, интерфейс или тип источника к вызываемому:

1
2
3
4

$myCasters = [
    'FooClass' => $myFooClassCallableCaster,
    ':bar resource' => $myBarResourceCallableCaster,
];

Как можно заметить, типы источников снабжаются префиксом : для предотвращения коллизий с именем класса.

Поскольку объект имеет один основной класс и потенциально много родительских классов или интерфейсов, к одному объекту может быть применено множество кастеров. В этом случае кастеры вызываются последовательно, начиная с кастеров, привязанных к интерфейсам, родительским классам и затем к главному классу. Несколько кастеров могут быть зарегистрированы для одного и того же типа источника/класса/интерфейса. Они вызываются в порядке регистрации.

Кастеры отвечают за возврат свойств клонируемого объекта или иисточника в виде массива. Они являются вызываемыми, принимающими пять аргументов:

• приводимый объект или ресурс;
• массив, смоделированный для объектов по образцу нативного оператора приведения PHP (array);
• объект Stub, представляющий основные свойства объекта (класс, тип и т.д.);
• true/false, когда кастер вызывается вложенным в структуру или нет;
• битовое поле Caster константы ::EXCLUDE_*.

Вот простой кастер, который ничего не делает:

1
2
3
4
5
6
7
8

use Symfony\Component\VarDumper\Cloner\Stub;

function myCaster(mixed $object, array $array, Stub $stub, bool $isNested, int $filter): array
{
    // ... наполнить/изменить $array в соответствии с вашими нуждами

    return $array;
}

Для объектов параметр $array заполняется с помощью нативного оператора приведения PHP (array) или возвратного значения $object->__debugInfo(), если магический метод существует. Затем возвратное значение одного кастера передается в качестве аргумента массива следующему кастеру в цепочке.

При приведении с помощью оператора (array) PHP добавляет к защищённым свойствам префикс \0*\0, а к приватным - класс, которому принадлежит свойство. Например, \0Foobar\0 будет префиксом для всех приватных свойств объектов типа Foobar. Кастеры следуют этому соглашению и добавляют еще два префикса: \0~\0 для виртуальных свойств и \0+\0 для динамических (добавляемых во время прогона свойств, отсутствующих в объявлении класса).

1
2
3
4
5
6
7
8
9

use Symfony\Component\VarDumper\Caster\LinkStub;
use Symfony\Component\VarDumper\Cloner\Stub;

function ProductCaster(Product $object, array $array, Stub $stub, bool $isNested, int $filter = 0): array
{
    $array['brochure'] = new LinkStub($array['brochure']);

    return $array;
}