Development Tools and Variable Dumping

This document covers the variable dumping infrastructure in Hypervel Foundation, which enhances Symfony's VarDumper component with source file resolution and editor integration. The system provides development-time debugging utilities that automatically display the file and line number where dump() calls originate, with clickable links to open files in configured editors.

For information about other development utilities like console commands, see Console Kernel and Command Execution. For testing-specific debugging tools, see Test Response Assertions.

Overview and Architecture

The variable dumping system extends Symfony VarDumper with automatic source resolution and context-aware formatting. The FoundationServiceProvider registers custom dumpers that detect whether code is running in CLI or HTTP contexts and format output accordingly.

Dumper Registration Flow

Sources: src/Providers/FoundationServiceProvider.php181-201

Component Architecture

Sources: src/Providers/FoundationServiceProvider.php181-201 src/Http/HtmlDumper.php14-115 src/Console/CliDumper.php16-103

Dumper Registration

The FoundationServiceProvider registers the appropriate dumper during service registration based on environment detection.

Environment Detection

Environment Variable	Behavior
VAR_DUMPER_FORMAT=html	Forces HTML dumper
VAR_DUMPER_FORMAT=cli	Forces CLI dumper
VAR_DUMPER_FORMAT=server	Disables custom dumpers (uses Symfony defaults)
VAR_DUMPER_FORMAT=tcp://...	Disables custom dumpers (uses Symfony server mode)
Not set	Auto-detects: php_sapi_name() === 'cli' ? CLI : HTML

The registration logic at src/Providers/FoundationServiceProvider.php194-200 uses a match expression to select the appropriate dumper:

match (true) {
 $format == 'html' => HtmlDumper::register($basePath, $compiledViewPath),
 $format == 'cli' => CliDumper::register($basePath, $compiledViewPath),
 $format == 'server' => null,
 $format && parse_url($format, PHP_URL_SCHEME) == 'tcp' => null,
 default => php_sapi_name() === 'cli' ? CliDumper::register(...) : HtmlDumper::register(...),
}

Custom Casters Configuration

Before registering dumpers, the provider configures custom casters at src/Providers/FoundationServiceProvider.php183-186 to hide internal properties of framework objects:

Class	Caster	Purpose
ConnectionInterface	StubCaster::cutInternals	Hide database connection internals
Container	StubCaster::cutInternals	Hide DI container internal state
Dispatcher	StubCaster::cutInternals	Hide event dispatcher internals
Grammar	StubCaster::cutInternals	Hide query grammar internals

Sources: src/Providers/FoundationServiceProvider.php181-201

Source Resolution System

The ResolvesDumpSource trait provides functionality to identify where a dump() call originated in the codebase, enabling the dumpers to display file and line information.

Resolution Algorithm

Sources: src/Concerns/ResolvesDumpSource.php56-113

Adjustable Traces

The trait maintains a static array $adjustableTraces at src/Concerns/ResolvesDumpSource.php40-42 that maps specific files to trace offsets:

File Pattern	Offset	Reason
symfony/var-dumper/Resources/functions/dump.php	1	The global dump() function adds an extra frame

When the backtrace includes these files, the algorithm adds the specified offset to find the actual caller location.

Compiled View Handling

When the resolved source file is a compiled view (detected via src/Concerns/ResolvesDumpSource.php118-125), the system extracts the original template path at src/Concerns/ResolvesDumpSource.php130-139:

protected function getOriginalFileForCompiledView(string $file): string
{
 preg_match('/\/\*\*PATH\s(.*)\sENDPATH/', file_get_contents($file), $matches);
 
 if (isset($matches[1])) {
 $file = $matches[1];
 }
 
 return $file;
}

This searches for the /**PATH ... ENDPATH*/ comment that Hyperf's view compiler adds to track the original template file. The line number is set to null since line mappings between compiled and original files are not maintained.

Custom Resolution

Applications can override the default resolution behavior using two static methods:

Method	Signature	Purpose
resolveDumpSourceUsing()	(callable(): ?array): void	Provide custom resolution logic
dontIncludeSource()	(): void	Disable source resolution entirely

Sources: src/Concerns/ResolvesDumpSource.php9-190

HTML Dumper Implementation

The HtmlDumper class extends Symfony's HtmlDumper to add source information to dumps in HTTP contexts.

Dump Output Injection

Sources: src/Http/HtmlDumper.php65-94

Separator Constants

The HtmlDumper defines two injection points at src/Http/HtmlDumper.php23-30:

Constant	Value	Use Case
EXPANDED_SEPARATOR	'class=sf-dump-expanded>'	Multi-line dumps with expanded output
NON_EXPANDED_SEPARATOR	"\n</pre><script>"	Single-line compact dumps

The dumper searches for these strings in the generated HTML and inserts the source information at the appropriate location.

Source HTML Generation

The getDumpSourceContent() method at src/Http/HtmlDumper.php99-114 generates the HTML snippet:

protected function getDumpSourceContent(): string
{
 if (is_null($dumpSource = $this->resolveDumpSource())) {
 return '';
 }
 
 [$file, $relativeFile, $line] = $dumpSource;
 
 $source = sprintf('%s%s', $relativeFile, is_null($line) ? '' : ":{$line}");
 
 if ($href = $this->resolveSourceHref($file, $line)) {
 $source = sprintf('<a href="%s">%s</a>', $href, $source);
 }
 
 return sprintf('<span style="color: #A0A0A0;"> // %s</span>', $source);
}

The output format is: <span style="color: #A0A0A0;"> // path/to/file.php:123</span> with an optional <a> wrapper if editor integration is configured.

Reentrancy Protection

The $dumping flag at src/Http/HtmlDumper.php35 prevents infinite recursion if the dump operation itself triggers additional dumps (e.g., if a __debugInfo() method calls dump()). Nested dumps bypass source injection.

Sources: src/Http/HtmlDumper.php14-115

CLI Dumper Implementation

The CliDumper class provides console-formatted output with ANSI colors and terminal hyperlinks.

Output Construction Flow

Sources: src/Console/CliDumper.php58-76

Console Output Format

The getDumpSourceContent() method at src/Console/CliDumper.php81-97 generates ANSI-formatted output:

protected function getDumpSourceContent(): string
{
 if (is_null($dumpSource = $this->resolveDumpSource())) {
 return '';
 }
 
 [$file, $relativeFile, $line] = $dumpSource;
 
 $href = $this->resolveSourceHref($file, $line);
 
 return sprintf(
 ' <fg=gray>// <fg=gray%s>%s%s</></>',
 is_null($href) ? '' : ";href={$href}",
 $relativeFile,
 is_null($line) ? '' : ":{$line}"
 );
}

The format uses Symfony Console's formatting syntax: <fg=gray> for color and ;href={url} for clickable terminal links in supported terminals.

Color Support Detection

The dumper determines color support at src/Console/CliDumper.php99-102 using the ConsoleOutput decorator status:

protected function supportsColors(): bool
{
 return $this->output->isDecorated();
}

This respects terminal capabilities and the --no-ansi flag automatically.

Sources: src/Console/CliDumper.php16-103

Editor Integration

Both dumpers support generating clickable links that open files in configured editors.

Editor Configuration

The resolveSourceHref() method at src/Concerns/ResolvesDumpSource.php146-171 reads configuration from config('app.editor'). The configuration supports two formats:

String Format:

Array Format:

Built-in Editor URLs

The trait defines URL schemes for common editors at src/Concerns/ResolvesDumpSource.php16-33:

Editor	URL Scheme
atom	atom://core/open/file?filename={file}&line={line}
cursor	cursor://file/{file}:{line}
emacs	emacs://open?url=file://{file}&line={line}
idea	idea://open?file={file}&line={line}
phpstorm	phpstorm://open?file={file}&line={line}
sublime	subl://open?url=file://{file}&line={line}
textmate	txmt://open?url=file://{file}&line={line}
vscode	vscode://file/{file}:{line}
vscode-insiders	vscode-insiders://file/{file}:{line}
vscode-remote	vscode://vscode-remote/{file}:{line}
vscodium	vscodium://file/{file}:{line}
xdebug	xdebug://{file}@{line}

Base Path Remapping

When the base_path option is provided, the dumper replaces the application's basePath with the configured path at src/Concerns/ResolvesDumpSource.php162-164:

if ($basePath = $editor['base_path'] ?? false) {
 $file = str_replace($this->basePath, $basePath, $file);
}

This enables remote development scenarios where the local filesystem path differs from the path in the editor (e.g., Docker containers, remote SSH development).

URL Generation

The final URL is generated at src/Concerns/ResolvesDumpSource.php166-170 by replacing placeholders:

return str_replace(
 ['{file}', '{line}'],
 [$file, (string) ($line ?? 1)],
 $href,
);

If no line number is available (e.g., for compiled views), it defaults to line 1.

Sources: src/Concerns/ResolvesDumpSource.php9-190

Integration Points

Service Provider Registration

The dumper registration occurs during the register() phase of FoundationServiceProvider at src/Providers/FoundationServiceProvider.php65 ensuring dumpers are available before any service provider's boot() method executes.

VarDumper Handler Setup

Both dumper classes follow the same registration pattern:

The VarDumper::setHandler() call at src/Http/HtmlDumper.php59 and src/Console/CliDumper.php52 registers a closure that:

1. Clones the variable using VarCloner
2. Passes the cloned data to dumpWithSource()

ReflectionCaster Configuration

Both dumpers configure the cloner at src/Http/HtmlDumper.php55 and src/Console/CliDumper.php48 to hide closure file information:

$cloner = tap(new VarCloner())->addCasters(ReflectionCaster::UNSET_CLOSURE_FILE_INFO);

This prevents dumping internal Reflection metadata about closures, keeping output focused on application data.

Sources: src/Http/HtmlDumper.php53-60 src/Console/CliDumper.php46-53 src/Providers/FoundationServiceProvider.php181-201