Getting Started

Install it as a dev dependency if you only use it for local debugging and test diagnostics:

composer require --dev mindplay/readable

If you plan to use it in exception rendering, production log messages, or Artisan command output, install it as a regular dependency instead.

There is no Laravel service provider, facade, config file, or publishable assets. The package is a small plain-PHP utility. Look first at:

vendor/mindplay/readable/README.md
vendor/mindplay/readable/src/Readable.php

The primary entry points are Readable::value() for formatting a value and Readable::type() for describing its type. A first practical use case is replacing noisy var_dump() / print_r() output while inspecting complex Laravel values:

use mindplay\readable\Readable;

// php artisan tinker
$user = App\Models\User::with('roles.permissions')->first();

dump(Readable::value($user->toArray()));
dump(Readable::type($user));

That is the sweet spot: quickly understanding nested arrays, DTOs, Eloquent attributes, closures, resources, and other values that are awkward to inspect with var_export().

Implementation Patterns

Local debugging and Tinker

Use Readable::value() when you need a compact human summary rather than a full dump:

use mindplay\readable\Readable;

dump(Readable::value($request->validated()));
dump(Readable::value($job->payload()));
dump(Readable::type($exception));

It is especially useful in php artisan tinker because the output is readable in a terminal, unlike deeply nested var_dump() output.

Logging context

For structured logs, prefer passing raw arrays to Laravel/Monolog and let the logger normalize them. Use Readable when you need a formatted string inside a message:

use Illuminate\Support\Facades\Log;
use mindplay\readable\Readable;

if (app()->environment('local')) {
    Log::debug('Import row rejected', [
        'row' => Readable::value($row),
        'type' => Readable::type($row),
    ]);
}

Guard expensive formatting behind an environment or debug check. Building a large readable string eagerly is wasted work if the log level discards it.

Exception messages and reporting

Attach readable context to custom exceptions or in your exception handler:

use mindplay\readable\Readable;

throw new InvalidArgumentException(
    'Unexpected payload: ' . Readable::value($payload)
);

For broader reporting, format selected context in App\Exceptions\Handler or a custom exception renderer. Keep secrets out of the formatted value before it reaches logs or HTTP responses.

Test diagnostics

Use it to make PHPUnit/Pest failures easier to understand:

use mindplay\readable\Readable;

$this->assertSame(
    $expected,
    $actual,
    'Actual value: ' . Readable::value($actual)
);

This is particularly helpful for data-provider-driven tests, nested arrays, and DTO comparisons where PHPUnit's default diff is less informative.

Artisan commands

Format values for command output:

use mindplay\readable\Readable;

$this->line(Readable::value($report));
$this->line('Type: ' . Readable::type($report));

This works well for diagnostics commands, import/export previews, and local maintenance scripts.

Blade and debug views

Because Blade escapes {{ }} output, Readable::value() is safe to use in a debug view:

<pre>{{ \mindplay\readable\Readable::value($payload) }}</pre>

Avoid {!! !!} unless you explicitly control the value, since the formatted output is meant for humans and may contain characters that should remain escaped.

Wrap it for redaction and consistency

Readable is static and has no Laravel integration. If you use it across a codebase, wrap it in a small service or helper so you can add redaction and truncation:

namespace App\Support;

use mindplay\readable\Readable;

final class DebugValue
{
    public static function format(mixed $value): string
    {
        return Readable::value(self::redact($value));
    }

    private static function redact(mixed $value): mixed
    {
        // Remove passwords, tokens, authorization headers, etc.
        return $value;
    }
}

This also gives you a single place to swap the formatter later without touching every call site.

Gotchas and Tips

It is not a Laravel package. There is no auto-discovery, facade, config, or container binding. Import the class directly or wrap it.
Output is for humans, not machines. Do not parse Readable::value() output, use it as a serialization format, or assert against its exact string in tests unless you deliberately want a brittle assertion.
Redact before formatting. Formatting request payloads, headers, or model attributes can expose passwords, tokens, and PII in logs. Redact first, then format.
Watch size and depth. Large collections, recursive structures, and deeply nested payloads can produce very large strings. Prefer formatting a slice, a selected array, or a summary.
Be careful with Eloquent models. Formatting a model may trigger accessors or expose attributes. Prefer $model->toArray() or a selected subset, and ensure relations are loaded if they matter.
Do not format eagerly in hot paths. In production logging, check the environment or log level before building the string.
HTML escaping matters. In Blade, use escaped output. In API responses, only expose readable output in local/debug environments.
CLI and web formatting differ. Newlines look fine in Tinker or Artisan output but may be awkward in browser responses or single-line log formats.
Static API limits testability. If you need to mock or customize formatting, wrap Readable behind your own service or helper.
Package maturity is a consideration. With a small star count and no dependents, treat it as a focused utility. Pin the version and keep usage behind a wrapper so replacing it is easy.
Check the method signature in the installed version. The package is small and its surface area is limited; confirm whether the current release exposes only value() / type() or additional depth/limit options before relying on them.
Dev dependency deployment. If installed with --dev, it will not be present in a production build that runs composer install --no-dev. Install it normally if production exception rendering depends on it.

Overall, mindplay/readable is best treated as a lightweight developer-experience utility: valuable for Tinker sessions, test failure messages, local diagnostics, and carefully guarded debug logging, but not a replacement for Laravel's logging, dumping, or exception infrastructure.

Readable Laravel Package