Utility Bundle Laravel Package

Getting Started

The bundle is a Symfony package, so the "getting started" depends entirely on which framework you're actually running. Do that triage first — it determines everything else.

If you are on Symfony:

composer require nyrodev/utility-bundle

Symfony Flex usually auto-registers the bundle. If not, add it to config/bundles.php:

NyroDev\UtilityBundle\NyroDevUtilityBundle::class => ['all' => true],

Then look in this order:

1. src/Utility/ — the core. Static helper classes (string/slug, date formatting, array manipulation, file/image/HTML helpers). Usable immediately, no configuration.
2. src/Service/ and DependencyInjection/ — anything that needs the container or config. Check Configuration.php for YAML keys under nyro_dev_utility:.
3. src/Twig/, src/Form/, src/Entity/ (or src/Doctrine/) — reusable Twig extensions, form types, and entity traits/attributes.
4. README.md — nyroDev bundles document the service names and options there, but assume you'll be reading the source more than the docs.

If you are on Laravel — which is the stated stack:

Do not composer require it. The bundle registration, DI extension, config tree, Twig extensions, and Doctrine traits are all dead weight in a Laravel app. The only transferable part is the framework-agnostic code in src/Utility/. Clone the repo instead and read that directory:

git clone https://github.com/nyroDev/UtilityBundle /tmp/utility-bundle
# read src/Utility/ and copy the 2–4 classes you actually need

Drop the copied classes (with their MIT headers) under app/Support/Utility/ or a first-party internal/utility package, add a test, and move on.

First use case: pick one concrete thing the bundle does that Laravel natives don't — usually a specific date/locale formatter or a file/path helper. Verify it against Illuminate\Support\Str, Arr, Number, Illuminate\Filesystem, and Carbon before copying. If two or more survive the gap analysis, that's your shortlist; if fewer than two do, write them yourself and skip the whole exercise.

Implementation Patterns

Pattern 1 — Direct static calls (Symfony context). The utility classes are designed to be called statically from anywhere:

use NyroDev\UtilityBundle\Utility\StringUtility;

$slug = StringUtility::slugify($title);

This is fine for one-off scripts and admin screens. In application code, prefer wrapping it (Pattern 3) so you aren't spreading static call-sites across the codebase.

Pattern 2 — Twig extension registration (Symfony only). Extensions are registered via the bundle's service definitions; there is nothing to do per-template beyond installing the bundle. Usage looks like:

{{ some_value|nyro_helper }}

Laravel has no Twig integration, so these are non-transferable. If you're on Laravel and the helper logic underneath is useful, copy the extension's class methods, not the extension registration.

Pattern 3 — Facade wrapper (recommended for adopted helpers). Never let application code depend on the upstream class name directly. Wrap each adopted helper behind a thin internal facade with a contract test:

namespace App\Support\Utility;

class Slugs
{
    public static function from(string $title): string
    {
        // body adapted from nyrodev/utility-bundle, MIT — see NOTICE
        ...
    }
}

Now the call sites are stable, the upstream dependency can be dropped or swapped without touching them, and the wrapper is the seam where you add validation, logging, or a Stringable return type.

Pattern 4 — Doctrine trait reuse (Symfony only). The bundle ships traits for entities (timestamps, slugs, soft-delete-style behavior). These bind to Doctrine ORM entity conventions, not Eloquent. In Laravel you can read the trait for the column set and behavior, then implement the same thing with an Eloquent trait plus model events (saving, creating) — the code isn't portable, the design is.

Pattern 5 — Form types (Symfony only). src/Form/ contains reusable form types built on Symfony Forms. There is no equivalent in Laravel; the patterns (a transformer that normalizes input before validation) translate, the code does not.

Pattern 6 — Extract-and-own workflow. The workflow that actually pays off:

1. Enumerate the specific helpers you'd call.
2. Map each against Laravel natives + Carbon; delete the rows that are covered.
3. For survivors, copy the class into app/Support/Utility/, preserve the MIT header, add a NOTICE entry.
4. Write a test that pins the behavior you rely on (this is the contract).
5. Add a PHPStan run at your project's level.
6. Assign an owner and put a review date in the decision record.

Integration tip — if you insist on a live dependency (Symfony only): pin an exact version, not a range. There is no semver history to trust, and the classic failure mode for helper libraries is a patch bump that silently changes formatting or slug output.

Gotchas and Tips

The -bundle suffix is the whole story. Laravel has no bundle concept. The naming tells you the service definitions, DependencyInjection/Extension.php, and Configuration.php are Symfony-shaped and will do nothing useful for you. Assume the framework-agnostic subset is only src/Utility/ until you've proven otherwise by reading it.

Static methods are the main long-term cost. They are hard to mock, hard to inject, and invite call-site sprawl. Every helper you adopt needs a facade in front of it before it appears in more than one file — otherwise unwinding it later means touching every caller.

mbstring and intl assumptions. String and locale-formatting helpers commonly depend on them and behave differently when they're missing or when the locale is unset. Verify the extension is installed in the container, not just locally, and add a test that exercises the exact locale you deploy on.

Filesystem helpers and CWD. File/path helpers often assume a working directory, follow symlinks, or set permissions in ways that differ between your local checkout and the container. If you adopt any of them, test them with a path containing a symlink and a path containing spaces, and pass absolute paths at the call site.

No semver guarantees and no CVE response. Bus factor is one. There is no issue tracker to lean on and no notification path for a disclosed vulnerability. The mitigation is exact pinning plus an owner who reads the source on PHP upgrades — the deprecation that breaks you at upgrade time is discovered then, not before.

Static state leaking across tests. If any helper caches locale, formatter, or file state statically, your tests become order-dependent and fail in CI but not locally. Run the test suite with --order-by=random once after adopting anything to catch it early.

Do not install it as a live dependency on Laravel. If a specific helper is useful, vendor it with MIT attribution into your own namespace. This keeps the time saving and drops the supply-chain surface; a hybrid — calling upstream classes and maintaining a fork — produces divergence without ownership.

Write the decision record. With zero stars and zero dependents, every future new engineer and every future audit will re-ask "why is this here?" A one-paragraph ADR (what we took, why, who owns it, review date) is the difference between a quiet internal helper and a recurring code-review fight.

Extension points worth keeping. If you fork, keep the upstream namespace mapping in a NOTICE/README note so a future upgrade is a diff against the original file rather than a rewrite. If the upstream project ever picks up — unlikely, but cheap to check quarterly — the diff tells you instantly whether re-adopting the live dependency is worth revisiting.