Application Utils Core Laravel Package

Getting Started

mistralys/application-utils-core is a dependency-free PHP utility library, not a Laravel package in the framework sense: there is no service provider, facade, config file, or publishable assets. You install it and call static/instance helpers directly.

composer require mistralys/application-utils-core

Where to look first, in order:

1. vendor/mistralys/application-utils-core/README.md – the entry points that exist in your installed version.
2. vendor/mistralys/application-utils-core/src/ – namespaces are PSR-4 mapped; skim the directory tree before assuming a class path, since this library was split out of the larger application-utils bundle and some classes moved between the two.
3. The tests/ folder in the repository (or on GitHub) – the tests are the most reliable usage documentation for methods like RGBAColor.

The first use case you will realistically hit in a Laravel app is brand-color contrast: a tenant or settings row stores #F5C542, and you need to decide whether a button label renders light or dark.

use Mistralys\ApplicationUtilsCore\RGBAColor\RGBAColor;

$brand = RGBAColor::fromString($tenant->primary_color); // '#F5C542'

$label = $brand->isDark() ? '#FFFFFF' : '#111111';

That is exactly the code path 2.5.1 touches: setForceDark() and setForceLight() let you override the automatic luma detection when the computed answer is technically correct but wrong for your design system.

Implementation Patterns

Wrap it in a small value object, not scattered calls. The library is a low-level primitive; keep it out of Blade templates and controllers so you can swap it or add caching later.

final class BrandColor
{
    private RGBAColor $color;

    public function __construct(string $hex)
    {
        $this->color = RGBAColor::fromString($hex);
    }

    public function forceDark(): self
    {
        $clone = clone $this;
        $clone->color->setForceDark();
        return $clone;
    }

    public function foreground(): string
    {
        return $this->color->isDark() ? '#FFFFFF' : '#111111';
    }
}

Use the override when intent beats arithmetic. Luma detection answers "is this color mathematically light?". It cannot know that your marketing palette treats a mid-tone yellow as a dark surface for accessibility reasons, or that a pale grey in a dark theme should still be treated as light. That is the gap 2.5.1 closes:

$accent = RGBAColor::fromString(config('theme.accent'));

if (in_array($theme, ['midnight', 'high-contrast'], true)) {
    $accent->setForceDark();
}

$accent->isDark(); // now honours the override

The release also ships companion methods to remove and reset the override, so treat an override as a per-request decision rather than a permanent property of the color. Confirm the exact reset method names against the class once installed; symmetric APIs are the norm in this library but are not documented in the changelog itself.

Resolve colors once per request. Parsing hex/rgb strings is cheap but pointless inside loops. Resolve tokens in a service or a config-backed registry, then pass RGBAColor instances down.

A natural Laravel integration point is a Blade component or a @themeColor-style directive that emits both background and foreground:

<button style="background: {{ $bg }}; color: {{ $fg }}">Buy now</button>

This matters most where CSS variables and color-mix() are unavailable: transactional email templates, dompdf/snappy PDFs, and any HTML rendered inside SVG attributes.

Test the outputs, not the internals. Assert the chosen foreground hex for a table of brand colors, and add explicit cases for forced overrides. Those tests will catch behavior changes on minor version bumps.

Gotchas and Tips

• A luma override is not an accessibility guarantee. Perceived brightness and WCAG contrast ratio are different calculations. If you need to pass WCAG AA, compute the actual contrast ratio against the resolved foreground; use setForceDark()/setForceLight() to encode design intent, then still verify the pair.
• Overrides mutate the instance. A color object stored on a config repository, a singleton, or a static cache will carry its override into every subsequent consumer. Clone before forcing, as in the pattern above, and use the reset methods rather than "setting the opposite" if a third state (auto) exists.
• 2.5.1 is additive and patch-level. No removals, no signature changes, no deprecations. Bump it freely inside a ^2.5 constraint; there is nothing to migrate.
• Watch the version constraint against your PHP version. This family of libraries tracks modern PHP releases aggressively. If composer resolves an older release than you expect, run composer show mistralys/application-utils-core and compare the php requirement before assuming the new methods exist.
• Namespace confusion is the most common stumbling block. Older tutorials and Stack Overflow answers target application-utils, where RGBAColor and friends live under a different namespace than in the core split-out. When a class is "not found", check vendor/mistralys/application-utils-core/composer.json autoload paths rather than trusting a snippet.
• Debugging luma decisions: log the raw hex and the reported dark/light result together, and flag any color where an override is active. Without that, a later reader will see a bright color rendering dark text and assume a bug.
• Extension points are thin by design. There is no container binding to swap, so the clean extension seam is your own wrapper class or a custom enum for semantic tokens (surface, on-surface, accent). Keep library calls behind it and future upgrades stay mechanical.
• No config, no side effects. If you find yourself looking for a config file to publish, or a provider to register, you are in the wrong package; that is a sign the helper you want lives in a higher-level Mistralys bundle rather than the core.