README

Dumper 是一个简单易用的 PHP 变量转储工具。

本质上，它是 print_r() 和 var_dump() 的替代品。

使用方法

使用 composer require gerardpastor/dumper 安装最新版本

启用所有转储功能，只需在主 Dumper 类上调用 enable() 方法即可

use Deg\Dumper\Dumper;

Dumper::enable(Dumper::BROWSER);

第一个参数确定使用哪种输出。这可以是预定义的字符串或 OutputInterface 的实例。

默认情况下，Dumper 包含 3 种输出：dummy、browser 和 console。

browser：将变量转储到浏览器（使用 HTML 格式化器）
console：将变量转储到控制台（使用控制台格式化器）
dummy：不进行转储（用于生产环境）

转储变量

Dumper 定义了 3 个转储函数

dumpVars：转储 $vars 中的每个变量

// dumpVars(array $vars, $deep = null)

$vars = array(
    'text',
    123,
    array(),
);

dumpVars($vars);

dump：转储 $var

// dump($var, $deep = null)

$var = 'foo';

dump($var);

dumpAll：转储每个参数

// dumpAll($var, $_ = null)

$var1 = 'foo';
$var2 = 'var';

dumpAll($var1, $var2);

所有以 "e" 开头的函数都会转储并结束执行。

edumpVars(array('text', 123, array()));

// Or
edump('foo', 1);

// Or
edumpAll('foo', 'var');

转储堆栈跟踪

您可以使用 dumpBacktrace() 转储当前的调试堆栈跟踪

// dumpBacktrace($limit = null)

dumpBacktrace();

// Or
edumpBacktrace();

原始 var_dump

此外，Dumper 还提供了 rawDump 函数，该函数在 <pre> 标签内执行原生 var_dump。

rawDump('foo', 'var');

配置

您可以在 Dumper 上配置一些默认参数。

访问 Dumper 实例

要配置 Dumper，您必须访问其实例。

在调用 enable() 时可以访问 dumper 实例，或者在 Dumper 已启用时通过调用 getInstance()。

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER);
$dumper->dump('foo');

$dumper = Dumper::getInstance();
$dumper->dump('foo');

设置默认的最大转储深度

您可以通过传递给 VarParser 来设置默认的最大转储深度

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER);
$dumper->getVarParser()->setMaxDeep(3);

// Dumps at 3 levels
dump($arrayOrObject);

您可以在调用 dump 或 dumpVars 时作为第二个参数覆盖此值

// Dumps at 2 levels
dump($arrayOrObject, 2);

限制堆栈跟踪中的堆栈帧数量

默认情况下，Dumper 会转储堆栈跟踪中的所有堆栈帧。您可以通过传递给 BacktraceFactory 来全局限制此数量

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER);
$dumper->getBacktraceFactory()->setMaxLimit(3);

// Dumps 3 stack frames
dumpBacktrace();

您可以在调用 dumpBacktrace 时作为第一个参数覆盖此值

// Dumps 2 stack frames
dumpBacktrace(2);

向堆栈跟踪添加排除项

Dumper 排除了所有命名空间和目录，但您可以通过传递给 BacktraceFactory 来添加自己的排除项

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER);
$dumper->getBacktraceFactory()->addExcule('Foo/Var');

//Or
$dumper->getBacktraceFactory()->addExcule(__DIRECTORY__ . '/foo/var');

禁用全局函数

通过在调用 enable() 时将第二个参数传递为 false，您可以禁用 Dumper 作为全局函数的定义

然后，您仍然可以直接在 dumper 实例上调用 dumper 函数来访问 dumper 函数

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER, false);

$dumper->dump('foo');

您可以在任何时间通过调用 defineGlobalFunctions() 来启用全局函数

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER, false);
Dumper::defineGlobalFunctions();

dump('foo');

变量分词器

Dumper 使用分词器将任何变量转换为字符串。

分词器接收一个变量并返回一个 TokenStream（即 Token 的集合）

Dumper 提供了分词器来解析最通用的变量类型

ObjectTokenizer：解析对象
ArrayTokenizer：解析数组
StringTokenizer：解析字符串
GenericTokenizer：解析任何变量（以一种非常简单的方式）

分词器具有 accept($var) 和 getConfidence() 方法。

解析器将使用接受给定变量的分词器，而不是那些接受分词器的。

自定义分词器

您可以通过添加自定义分词器来添加更具体或更复杂的解析。

为此，您必须创建一个实现 TokenizerInterface 的类，并将其传递给 VarParser。

namespace Foo\Var;

use Deg\Dumper\Parser\VarParser;
use Deg\Dumper\Parser\TokenStream;
use Deg\Dumper\Parser\TokenStreamBuilder;

class MyCustomTokenizer implements TokenizerInterface
{
    public function tokenize($var, $deep, VarParser $parser)
    {
        $type = gettype($var);

        $builder = new TokenStreamBuilder();

        // Build the stream using a TokenStreamBuilder
        $builder
            ->addKeyword($type)
            ->addBrace('(')
            ->addNumber($var)
            ->addBrace(')')
        ;

        // Tokenizer must return a TokenStream
        return $builder->getStream();
    }

    public function accept($var)
    {
        // It establishes if this tokenizer can tokenize the given variable
        return is_number($var);
    }

    public function getConfidence()
    {
        // It defines how specific is this tokenizer (higher number means more specific)
        return 20;
    }

}

然后，将其传递给 VarParser

use Deg\Dumper\Dumper;

$dumper = Dumper::enable(Dumper::BROWSER);
$dumper->getVarParser()->addTokenizer(new Foo\Var\MyCustomTokenizer());

请参阅提供的分词器以获取更多具体示例。

输出

输出器可以使用不同的输出方式向用户显示变量。

提供的输出方式有：

BrowserOutput：将解析结果打印到浏览器（类似于 var_dump）
ConsoleOutput：将解析结果打印到系统控制台（php://stdout，php://output）
NullOutput：不打印任何内容。可以在生产环境中防止输出任何变量。

使用自定义输出

您可以通过扩展 Output 类来提供自己的输出

namespace Foo\Var;

class MyCustomOutput extends Output
{
    public function __construct(FormatterInterface $formatter = null)
    {
        $formatter = $formatter ? : new HtmlFormatter();

        parent::__construct($formatter);
    }

    protected function doWrite($message)
    {
        print $message;
    }
}

然后使用它

use Deg\Dumper\Dumper;

$output = new Foo\Var\MyCustomOutput;

$dumper = Dumper::enable($output);
// or

$dumper->setOutput($output);

查看提供的输出以获取更多具体示例。

格式化器

输出使用格式化器来格式化响应。提供的输出有：

HtmlFormatter：将结果格式化为HTML代码。
ConsoleFormatter：将结果格式化为控制台代码。
PlainFormatter：仅格式化字符，如换行符或缩进。

使用自定义格式化器

您可以通过实现 FormatterInterface 接口来提供自己的格式化器

namespace Foo\Var;

class MyCustomFormatter implements FormatterInterface
{
    public function formatStream(TokenStream $stream)
    {
        $buffer = '';

        while ($stream->hasNext()) {
            $token = $stream->getNext();
            $buffer .= $this->formatToken($token);
        }

        return $buffer;
    }

    public function formatToken(Token $token)
    {
        return $token->getDescription() ?: $token->getValue();
    }
}