Установка

1

$ composer require symfony/var-dumper --dev

Як варіант, ви можете клонувати репозиторій https://github.com/symfony/var-dumper.

Функція 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 у звичайному виведенні.

Сервер скидань

Функція 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:

1
2
3

# config/packages/debug.yaml
debug:
   dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%"

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

<!-- config/packages/debug.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:debug="http://symfony.com/schema/dic/debug"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/debug
        https://symfony.com/schema/dic/debug/debug-1.0.xsd"
>
    <debug:config dump-destination="tcp://%env(VAR_DUMPER_SERVER)%"/>
</container>

1
2
3
4
5
6
7
8

// config/packages/debug.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container) {
    $container->extension('debug', [
        'dump_destination' => 'tcp://%env(VAR_DUMPER_SERVER)%',
    ]);
};

Поза додатком Symfony використовуйте клас ServerDumper:

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

require __DIR__.'/vendor/autoload.php';

use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\CliDumper;
use Symfony\Component\VarDumper\Dumper\ContextProvider\CliContextProvider;
use Symfony\Component\VarDumper\Dumper\ContextProvider\SourceContextProvider;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;
use Symfony\Component\VarDumper\Dumper\ServerDumper;
use Symfony\Component\VarDumper\VarDumper;

$cloner = new VarCloner();
$fallbackDumper = \in_array(\PHP_SAPI, ['cli', 'phpdbg']) ? new CliDumper() : new HtmlDumper();
$dumper = new ServerDumper('tcp://127.0.0.1:9912', $fallbackDumper, [
    'cli' => new CliContextProvider(),
    'source' => new SourceContextProvider(),
]);

VarDumper::setHandler(function ($var) use ($cloner, $dumper) {
    $dumper->dump($cloner->cloneVar($var));
});

Потімм ви можете використати наступну команду, щоб запустити готовий до використання сервер:

1
2

$ ./vendor/bin/var-dump-server
  [OK] Server listening on tcp://127.0.0.1:9912

1

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

1

$ VAR_DUMPER_FORMAT=server [your-cli-command]

Інтеграція DebugBundle та Twig

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

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

Але якщо панель інструментів не можна відобразити так як ви, наприклад, викликали die()/exit()/dd() або виникла фатальна помилка, тоді скидання пишуться у звичайному потоці виведення.

В шаблоні Twig доступні дві конструкції для скидання змінної. Вибір між ними в основному залежить від ваших особистих вподобань, і все ж:

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

Цю поведінку моожна змінити, сконфігурувавши опцію debug.dump_destination. Прочитайте більше про це та інші опції в довіднику конфігурації DebugBundle.

Використання компонента VarDumper у вашому наборі тестів PHPUnit

Компонент VarDumper надає a trait, який може допомогти написати деякі з ваших тестів для PHPUnit.

Це надасть вам два нових твердження:

assertDumpEquals()

веріфікує, щоб скидання змінної, надане в якості другого аругменту, відповідало очікуваному скиданню, наданому в якості першого аргументу.

assertDumpMatchesFormat()

такий же, як і попередній метод, але приймає заповнювачі у очікуваному скиданні, заснованому на методі assertStringMatchesFormat(), наданому PHPUnit.

VarDumperTestTrait також містить інші методи:

setUpVarDumper()

використовується для конфігурації доступних кастерів та їх опцій, що є способом лише контролю очікуваних вами полів та дозволяє писати лаконічні тести.

tearDownVarDumper()

викликається автоматично після кожного випадку, щоб скинути конфігурацію за замовчуванням, створену в setUpVarDumper().

Приклад:

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);
    }
}

Приклади скидання та виведення

Для простих змінних, читання виведення має бути прямолінійним. Ось деякі приклади, що відображують першу змінну, визначену в 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);

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);

1
2
3
4
5
6
7
8
9

class PropertyExample
{
    public $publicProperty = 'Префікс `+` денотує публічні властивості,';
    protected $protectedProperty = '`#` - захищені, а `-` - приватні.';
    private $privateProperty = 'Наведення на властивість демонструє нагадування.';
}

$var = new PropertyExample();
dump($var);

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);

1
2
3
4
5
6
7

class ReferenceExample
{
    public $info = "Циклічні та споріднені посилання відображаються як `#number`.\n Наведення на них виділяє всі екземпляри в одному скиданні.\n";
}
$var = new ReferenceExample();
$var->aCircularReference = $var;
dump($var);

1
2
3
4
5
6
7

$var = new \ErrorException(
    "Для деяких обʼєктів властивості мають спеціальні значення,\n"
    ."які найкраще відображаються у вигляді обмежень, на кшталт\n"
    ."`severity` нижче. Наведення на них відображає значення (`2`).\n",
    E_WARNING
);
dump($var);

1
2
3
4
5
6
7
8

$var = array();
$var[0] = 1;
$var[1] =& $var[0];
$var[1] += 1;
$var[2] = array("Жорсткі посилання (циклічні або споріднені)");
$var[3] =& $var[2];
$var[3][] = "скидаються з використанням префіксів `&number`.";
dump($var);

1
2
3
4
5

$var = new \ArrayObject();
$var[] = "Деякі джерела та спеціальні обʼєкти, як поточний,";
$var[] = "іноді краще за все представити, використовуючи віртуальні";
$var[] = "властивості, що описують їх внутрішній стан.";
dump($var);

1
2
3
4
5
6
7
8

$var = new AcmeController(
    "Коли скидання перевищує максимальний ліміт обʼєктів\n"
    ."або коли зустрічаються спеціальні обʼєкти,\n"
    ."діти можуть бути замінені еліпсами та опціонально\n"
    ."мати число, яке повідомляє як і скільки було\n"
    ."видалено; В цьому випадку - `9`.\n"
);
dump($var);

Дізнайтеся більше