Util Bundle Laravel Package

Getting Started

kitpages/util-bundle is a Symfony 2/3-era bundle of small helpers extracted from KitpagesCmsBundle — not a Laravel package. It has no service provider, no facade, no config/*.php to publish, and no php artisan vendor:publish story. The correct first step is therefore not composer require.

Minimal steps (timebox: ~15 minutes):

1. Read composer.json before anything else. Look at the php constraint and the symfony/* requirements. If you see symfony/symfony: ~2.x, ~3.x, or component constraints like symfony/http-kernel: ^2.8, stop — Laravel 10/11 already pins Symfony 6/7 components and Composer will deadlock. composer require in a Laravel app is not the path; clone or download the tarball.

2. Map the bundle's surface, in this order:

   • DependencyInjection/*Extension.php — reveals the config alias (kitpages_util or similar) and every registered service.
   • Resources/config/services.yml (or .xml) — the fastest inventory of what you actually get.
   • Twig/ — anything extending Twig_Extension / AbstractExtension is the template-level surface.
   • Util/, Service/, Helper/ — plain PHP classes. These are the only things worth extracting.

3. Classify each class into three buckets:

   • Pure PHP, no container → candidate for extraction.
   • Needs container / kernel / request → skip; rewrite in Laravel terms.
   • Twig-coupled → skip; rewrite as a Blade directive or a view composer.

4. First use case. Pick a single helper you are currently hand-rolling — string truncation with ellipsis, an array "get by dot path", a date/number formatter — and reimplement it in app/Support/ with your own namespace. Laravel autoloads app/ via PSR-4 automatically, so there is nothing to wire. Write a test that pins the output before you delete the reference implementation.

That's the whole "getting started": a source audit with an extraction decision, not an install-and-configure flow.

Implementation Patterns

Vendor-and-extract, not install. The dominant pattern is: inspect, copy the handful of pure-PHP helpers into app/Support/, rename the namespace, add tests, and keep a NOTICE/README note pointing at the original MIT-licensed source. You own the code from that moment, which is the honest trade — 4 stars and 0 dependents means no upstream is coming to help you anyway.

Map to framework primitives first. Before extracting anything, check whether Laravel already covers it:

Only extract when there is no equivalent, or when byte-for-byte output compatibility matters (e.g. migrating legacy CMS-rendered content where truncation length, encoding, or number separators must match exactly). In that case, characterization tests are mandatory — snapshot the old output, assert the new implementation matches.

Adapter, don't scatter. Never call extracted helpers directly from controllers or Blade. Put one class in front:

namespace App\Support;

class Formatter
{
    public static function truncate(string $value, int $len = 50): string
    {
        // delegate to the extracted helper, or to Str::limit
    }
}

If the helper is ever replaced (or you decide to drop it), you change one file instead of fifty call sites. This also gives you a seam to normalize behaviour differences between the 2013 original and PHP 8.

Translating the Twig layer. The bundle's Twig extensions do not register in Laravel. Port each filter as a Blade directive or a small helper:

// app/Providers/AppServiceProvider.php
Blade::directive('truncate', fn ($expr) => "<?php echo e(App\\Support\\Formatter::truncate($expr)); ?>");

Keep the same division of labour the original bundle intended: formatting belongs in the view, business logic does not.

If you are genuinely forced to run the Symfony bundle (e.g. maintaining an existing KitpagesCMS deployment alongside Laravel), do it behind a bridge: instantiate the pure-PHP classes manually in a service provider and bind them into the container. Do not attempt to register a Symfony Bundle subclass or boot an HttpKernel inside Laravel — the kernel/bundle registration model has no seam in Laravel's lifecycle.

Configuration. There is no Laravel config to publish. Anything the Symfony Configuration.php tree exposed should become a config/util.php entry with env()-backed defaults, read via config('util.*') — never a hardcoded constant in an extracted class.

Gotchas and Tips

Composer resolution will fail, not warn. The bundle's symfony/* constraints predate Laravel's pinned Symfony components. Attempting composer require typically produces a resolution deadlock rather than a clean error, and --ignore-platform-reqs will get you a boot-time failure instead. Download the source; do not add it to composer.json.

Assume PHP 8 breakage in every extracted file. Grep for the usual suspects before running anything: each(, create_function, ${var} string interpolation, curly-brace string offsets $str{0}, utf8_encode/utf8_decode, and implicit nullable parameters (function f(string $x = null)). Also watch for dynamic property creation, which fires a deprecation on PHP 8.2+.

Silent encoding bugs. Helper-era libraries frequently use strlen/substr/strtoupper on UTF-8 input. If a truncation helper produces mangled multibyte output, that is mb_* missing, not a logic error. Test with accented characters and CJK before shipping.

Container coupling hides in small places. Before declaring a class "pure PHP", grep it for Container, Kernel, getContainer(), Request, $GLOBALS, and $_SERVER. Anything that reads them is effectively a service; rewriting it as a Laravel service is faster than bridging it.

Symfony config validation is compile-time only. Undocumented keys under kitpages_util: fail at container compile, not at boot — so a typo surfaces as a confusing fatal in the wrong place. Since you are not using the tree anyway, this is only relevant if you go the bridge route: read Configuration.php rather than guessing key names.

Twig extension base class moved. \Twig_Extension was namespaced to \Twig\Extension\AbstractExtension in Twig 2. The bundle predates that. If you port the extension rather than replacing it with Blade, update the parent class and the getFilters() signature (TwigFilter objects, not ['name' => callable] arrays).

Keep the attribution, kill the dependency. MIT licensing makes vendoring clean. Drop a one-paragraph README.md in the extracted folder: original repo URL, commit SHA, license, date extracted, and what you changed. This is the single highest-value thing you can do — it prevents the next developer from rediscovering the package and repeating this entire evaluation.

Do not let it accrete. The extracted set should be a closed list. New utility needs go through Str/Arr/Carbon first; adding a sixth helper to a folder labelled "vendored from an abandoned bundle" is how internal Support/ namespaces turn into unowned libraries nobody wants to touch.

Debugging tip. Because documentation is essentially absent, the fastest way to understand a helper's real contract is to find how KitpagesCmsBundle calls it: argument shapes, edge cases handled at the call site, and which outputs downstream templates depend on. Treat the CMS as the spec, not the docblock.