Cloner

Клонировщик используется для создания среднего представления любой переменной 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 всегда поддаются сериализации.

Клонировщик применяет ограничения при создании представления, так что один может представляь только поднабор клонированной переменной. До вызова cloneVar(), вы можете сконфигурировать эти ограничения:

setMaxItems()

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

setMinDepth()

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

setMaxString()

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

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

withMaxDepth()

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

withMaxItemsPerDepth()

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

withRefHandles()

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

seek()

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

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

Dumper

Дампер ответственный за вывод представления строки переменной 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 ($line, $depth) use (&$output) {
        // Негативная глубина означает "конец сброса"
        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, array(
    // 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);

// (добавлена длина строки перед строкой)
// 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"
// ]

Caster

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

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

1
2
3
4
5
6
7
8

use Symfony\Component\VarDumper\Cloner\VarCloner;

$myCasters = array(...);
$cloner = new VarCloner($myCasters);

// или

$cloner->addCasters($myCasters);

Предоставленный аргумент $myCasters является массивом, соединяющим класс, интерфейс или тип источника с вызываемым:

1
2
3
4

$myCasters = array(
    'FooClass' => $myFooClassCallableCaster,
    ':bar resource' => $myBarResourceCallableCaster,
);

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

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

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

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

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

1
2
3
4
5
6
7
8

use Symfony\Component\VarDumper\Cloner\Stub;

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

    return $array;
}

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

При приведении опретаора (array), PHP добавляет к защищённым свойства префикс \0*\0, а к приватным - класс, владеющий свойством. Например, \0Foobar\0 будет префиксом для всех приватных свойств объектов типа Foobar. Casterы следуют этому соглашению и добавляют ещё два префикса: \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, Stub $stub, $isNested, $filter = 0)
{
    $array['brochure'] = new LinkStub($array['brochure']);

    return $array;
}