Php Util Laravel Package

Getting Started

Before composer require, verify what the package actually is — with a 0-star, 0-dependent repository the docs are the code.

1. Read composer.json on the default branch first. Two things decide your integration strategy:
   • autoload → psr-4 means namespaced classes; files means global functions are injected into every request (a much bigger commitment).
   • require.php → if it's below your Laravel/PHP floor, stop here.
2. Skim src/ end to end. It's a utility package; you should be able to read 100% of it in under 10 minutes. If you can't, that's your answer.
3. Check for tests and CI. No tests + no stars + no dependents = you are the QA team. Plan to write characterization tests (see below) before you depend on it anywhere important.
4. Install pinned, in a branch:

   composer require omnicode/php-util --prefer-dist
   composer show omnicode/php-util   # version, requires, autoload
   

   If there are no tags, Composer will pull dev-main. That's a red flag for reproducibility — pin the commit in composer.json ("omnicode/php-util": "dev-main#<sha>") rather than tracking a moving branch.

First use case. Pick one leaf operation where a tiny helper saves boilerplate — string slugging, array dot-access, number/byte formatting, a blank()/filled()-style check — and use it in a single service class. Do not start by sprinkling it through controllers and Blade views; you want a cheap, reversible pilot to judge whether the helper's semantics match your expectations.

Quick sanity probe before writing real code:

php -r "require 'vendor/autoload.php';
var_dump(class_exists('Omnicode\\\\Util\\\\Str'));       // adjust to the real namespace
print_r(get_defined_functions()['user']);               // see if it declared globals
"

The second line is the important one: it tells you exactly which function names the package has claimed process-wide.

Implementation Patterns

Pattern 1 — Wrap it before you spread it

Treat this package as an implementation detail behind your own adapter. This is the single highest-value pattern for an unvetted 0-star dependency, because it makes removal a one-file change.

// app/Support/Text.php
namespace App\Support;

final class Text
{
    public static function slug(string $value): string
    {
        return \Omnicode\Util\Str::slug($value); // wherever the real API lives
    }
}

// usage
Text::slug($post->title);

You get: a stable API you control, a place to add input guards, and a single seam to swap in Illuminate\Support\Str::slug() if you later decide the dependency isn't worth it.

Pattern 2 — Characterization tests first

Because the package ships no tests, pin its observed behavior so a future patch release can't silently change your output.

it('produces the slugs our routes depend on', function () {
    expect(Text::slug('Héllo, Wörld! 2025'))
        ->toBe('hello-world-2025'); // whatever it actually returns today
});

Cover the ugly inputs deliberately: empty string, null, unicode, very long strings, numeric strings, multibyte truncation boundaries. Utility packages fail on exactly these.

Pattern 3 — Layering inside Laravel

• FormRequests / validation: fine for normalization (trim, slug, case) after validation, not as a replacement for validation rules.
• Eloquent casts & accessors: good fit — a custom cast that delegates to the helper keeps models clean.
• Blade: avoid direct calls in templates. Use a view model, accessor, or Blade directive so the helper isn't reachable from arbitrary template code.
• Queues/Jobs: safe only if the helper is pure and doesn't depend on request state ($_SERVER, locale set by middleware, container bindings). Verify static state — a static memo cache in a long-running Octane/queue worker is a classic leak.

Pattern 4 — Make it removable

Add the wrapper, then run a grep gate in CI so direct package references don't creep in:

! grep -rn "Omnicode\\\\Util" app/ --include=*.php | grep -v "app/Support/"

Pattern 5 — Keep static analysis honest

If the package has no type declarations, PHPStan/Larastan will either skip it or spam errors. Write a small stub so your own code still gets checked:

# phpstan.neon
parameters:
    scanDirectories:
        - vendor/omnicode/php-util/src
    ignoreErrors:
        - identifier: missingType.return
          path: vendor/omnicode/php-util/*

Gotchas and Tips

Global function collisions are the #1 failure mode. If the package autoloads via files, its functions load on every request, before your code. If it declares str_slug() or array_get() — names that other abandoned utility packages also use — you get a fatal Cannot redeclare that only appears when both are installed. Inspect vendor/composer/autoload_files.php to see exactly what's globally registered:

php -r "print_r(require 'vendor/composer/autoload_files.php');"

Name-shadowing with Laravel's helpers. Illuminate\Support\Str, Arr, and Number already cover most "PHP utility" territory. If the package mirrors those names, you'll get confusing behavior differences (e.g. different slug transliteration tables, different Str::limit suffix handling). Decide on one source of truth per operation and note it in your team conventions.

dev-main drift. No tagged releases means composer update can change behavior without a version bump. Either pin the SHA, or commit a path-repository fork you control:

"repositories": [{ "type": "vcs", "url": "[email protected]:yourorg/php-util.git" }],
"require": { "omnicode/php-util": "dev-main" }

Audit and license. Run composer audit and confirm the license file exists. A package with no license is legally "all rights reserved" regardless of what GitHub shows — a real problem for commercial code even if it's technically just helpers.

Debugging odd output. Utility functions are usually pure, so when results look wrong the cause is almost always input encoding or locale. Check mb_internal_encoding(), and whether the helper calls mb_* or plain strlen/substr — byte-based implementations corrupt unicode silently rather than throwing.

Null and strict-types semantics. Many small utility libs predate declare(strict_types=1) and coerce silently ('' == 0, null → ''). Wrap calls with explicit guards in your adapter rather than trusting the helper to reject bad input.

Extension points are probably absent. Utility classes are typically final with private constructors. Don't plan on subclassing. Your extension point is the adapter from Pattern 1, or a fork — and a fork of a 30-file utility package is often cheaper than the dependency itself.

Never route security-sensitive work through it. Hashing, token generation, escaping, path sanitization, or anything touching user-supplied filenames. Unreviewed one-liners in those areas are how you get path traversal and weak randomness. Use Laravel's Hash, Str::random, e(), and Storage instead.

Migration tip. If the pilot goes well, keep it. If it doesn't, the wrapper means the swap is mechanical: replace the adapter bodies with framework primitives, delete the require line, run your characterization tests, and confirm green. Keep those tests even after removal — they document the behavior your app actually relies on.