Html Cli Dumper Bundle Laravel Package

Getting Started

Install and publish first.

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-config

Since v1.0.1 ships revised defaults, publish the config before writing any styling code — otherwise you will be coding against the package's internal fallbacks and will get a surprise when you later publish.

Where to look first, in order:

1. config/<package>.php — this is the centre of gravity for the package. v1.0.1 expanded the default configuration, so read it end-to-end before touching the API. The colour definitions, aliases, and any default/fallback keys are the contract you will be working against.
2. The package README's "Configuration" section — for the canonical list of supported colour formats (named, hex, RGB, ANSI 256).
3. The service provider — to see what is bound into the container and whether anything is resolvable as a singleton you can swap in tests.

First use case: define one palette entry in config and render it once, rather than hard-coding ANSI escapes in a command.

// config/<package>.php
'colors' => [
    'brand'   => '#4F46E5',
    'success' => 'green',
    'danger'  => 'red',
],

$this->line($package->color('brand')->apply('Deploying…'));

If that renders correctly in your terminal, the wiring is sound and you can move on to theming. If it renders as literal escape codes, jump straight to the Gotchas section — it is almost always a TTY or NO_COLOR issue, not a config issue.

Implementation Patterns

Treat config as the theme layer, code as the semantic layer. The healthiest pattern with this package is to never reference a raw colour in application code. Commands and views ask for brand, success, muted; the config maps those to concrete colours. That way v1.0.1-style default changes and future re-theming are a config diff, not a find-and-replace.

Per-environment palettes. Because the defaults are now more opinionated, override rather than replace:

// config/<package>.php
'colors' => array_merge([
    // keep package defaults for anything you don't care about
], [
    'brand' => env('APP_BRAND_COLOR', '#4F46E5'),
]);

This is the single most useful pattern for surviving minor releases — you inherit improved defaults for keys you never customised.

Centralise a palette class. Wrap the package in one small class so the rest of the app depends on your API, not the package's:

final class Palette
{
    public static function brand(string $text): string
    {
        return app(Colors::class)->color('brand')->apply($text);
    }
}

This is your extension point when the package's fluent API shifts, and it makes the package trivially fakeable in tests.

Console command workflow. Resolve the colour manager from the container in handle(), not in the constructor — config may not be fully loaded during command registration, and this keeps commands testable.

Testing pattern. Assert on semantic output, not escape sequences. Either strip ANSI in assertions or bind a no-op/stub implementation in the container:

$this->app->instance(Colors::class, new NullColors());

Anything that asserts on raw \e[38;5;… bytes will break on the next default-configuration change.

Blade/diagnostic output. If the package has a directive or helper for views, register the palette once in a service provider and keep colour names identical across console and web output so a single vocabulary covers both.

Migration pattern for 1.0.0 → 1.0.1. Diff your published config against the new stub (vendor:publish --force into a temp tag, or diff the package's config/ directory against yours). Port across any new keys by hand; do not blind-overwrite a customised config.

Gotchas and Tips

Re-publish deliberately, not reflexively. "Better default configuration" means the shipped stub changed. vendor:publish --force will silently discard your customisations. Diff first, merge second. If the package published versioned config or supports a --tag=<package>-config re-publish, prefer copying new keys into your existing file.

Config caching will hide your changes. After editing the palette, php artisan config:cache (or a stale cached config in a container image) is the number one reason "my colours didn't change". Always php artisan config:clear when debugging styling, and remember that env() calls inside config files return null once cached — read env values in the config file only, never at runtime.

Terminal capability varies more than you think. 24-bit hex colours degrade badly on 256-colour terminals and vanish entirely in CI logs, Docker build output, and piped output. Verify behaviour when stdout is not a TTY — many implementations auto-detect and disable colour, which will make your tests pass locally and your --no-ansi CI job look different. Support NO_COLOR and FORCE_COLOR conventions if the package does not already.

Never assert on raw escape codes. Even a patch release can change how a named colour is encoded. Assert on the semantic token or on stripped text.

Default changes are behavioural changes. Even without a breaking-change marker, a patch that touches defaults can alter output an existing test or a log-scraping pipeline depends on. Check whether any of your tests or downstream consumers parse coloured output; if so, pin the palette explicitly in config rather than relying on defaults.

Fallback behaviour deserves a test. With a richer colour model, unknown aliases or malformed hex values may throw, silently fall back, or render literally depending on configuration. Write one test per failure mode you care about — especially if APP_ENV=production must never throw on a typo'd colour name.

Extension points to know: the container binding for the colour manager (swap it in tests), the config file itself (theming), and any published view/stub assets. If the package registers a facade, prefer constructor/container injection in your own code so you are not coupled to the facade's static surface.

Debugging checklist when colour is wrong: (1) config:clear, (2) confirm the config key path actually exists in the new stub, (3) check TTY/NO_COLOR/--no-ansi, (4) verify the terminal supports the format you specified, (5) only then suspect the package.

Pin the version in composer.json (^1.0.1) and skim the changelog at each patch — this release is a good reminder that "default configuration" changes ship in patches, so treat minor colour drift as expected rather than a bug.