Twig Extension Bundle Laravel Package

Getting Started

This release is additive: two new named string filters (ucfirst, lcfirst) land alongside a composer constraint bump and a cosmetic code-style pass. Nothing is removed, so an existing install can upgrade in place.

1. Upgrade and pin: composer require <vendor>/<package>:^1.1. The "update composer requirements" entry in 1.1.0 means the floor for PHP/Laravel may have moved — run composer why-not <vendor>/<package> 1.1.0 before assuming the upgrade is blocked by your app rather than by the package's own constraints. If you are stuck on an older PHP or Laravel minor, stay on the 1.0.x line; the new filters are the only thing you lose.
2. Look at the README first. The broken link fixed in this release is usually the one pointing at the filter reference — that page is the authoritative list of registered filter names and their expected input types. Read it before grepping the source.
3. Find the registration point. Filters in packages like this are typically registered in a service provider or declared in a publishable config file. Locate that list and confirm ucfirst / lcfirst appear after upgrading (php artisan config:clear first if the list is config-driven and cached).
4. First use case: normalizing human-entered labels. A name field typed as jANE dOE is the classic target — pipe it through a lowercase normalizer then ucfirst for a display value, or through lcfirst when you are joining a greeting onto a proper noun ("dear " . lcfirst($title)).

Implementation Patterns

Treat filters as a formatting layer, not a validation layer. Apply ucfirst/lcfirst at the edge — presenters, API resources, Blade output — and keep raw input untouched in the database. This keeps the filters swappable and stops you from re-running migrations when formatting rules change.

Chain deliberately. The value of these two additions is composition: trim → lower → ucfirst for sentence-case display names, lower → ucfirst for e-mail local parts shown in admin UIs. Centralize the chain in one place (an accessor, a small Formatter/Presenter class, or a Blade component) rather than repeating it at each call site — otherwise the order drifts between screens and you get inconsistent casing.

Wrap them for testability. Call the filter through your own thin helper or enum of filter names so tests assert on intent (NameFormatter::display($input)) rather than on a package API you do not control. When the package changes again, one file moves.

Use data providers in tests. Casing filters have a wide input space — empty string, single char, all-caps, leading whitespace, unicode. A Pest/PHPUnit dataset of [input, expected] pairs is the cheapest way to pin behavior, and it documents what your app expects from the package.

Register your own filters in the same slot. Most packages of this shape expose a public registration contract; adding an app-specific filter (e.g. titleCase, initials) through the same mechanism keeps the calling convention consistent across built-in and custom filters. Do this in a dedicated service provider, not AppServiceProvider, so it stays discoverable.

Blade/directive integration: if your templates render user-supplied strings, apply the filter in the component class or view composer rather than inline in the template. Inline chains get copy-pasted and become untestable.

Gotchas and Tips

• ucfirst and lcfirst are byte-oriented, not multibyte-safe. PHP's native functions only touch the first byte. For UTF-8 input (accented names, CJK, emoji-leading strings) you want mb_*-based equivalents — Laravel's Str::ucfirst() / Str::lcfirst() use the multibyte polyfill and are the safer default. Check which implementation this package's filters wrap before relying on them for non-ASCII data; this is the single most likely source of "works in staging, breaks for one user" bugs.
• Order matters and mistakes are silent. ucfirst immediately followed by lcfirst is a no-op. lower → ucfirst gives Hello; ucfirst → lower gives hello. Write the chain once and never inline it.
• lcfirst on acronyms and brand names. lcfirst('NASA') → nASA. If the field can contain proper nouns or codes, guard the filter behind a check rather than applying it blanket-style.
• Composer constraint bump = the real risk in this release. The code-style commit is whitespace-only and the README fix is cosmetic, so if your upgrade fails or your test suite shifts, look at dependency resolution first: run composer update --dry-run <vendor>/<package> and read the constraint diff. Laravel major/PHP minor floors are the usual culprit.
• Clear caches after upgrading. If filters are listed in a published config, a cached config (bootstrap/cache/config.php) will hide the two new names and you will conclude the upgrade did not apply. php artisan config:clear && php artisan cache:clear.
• Name collisions. ucfirst/lcfirst may shadow or be shadowed by existing global helpers, Blade directives, or filters registered by other packages. If a filter resolves to the wrong implementation, dump the registry contents at boot to see who registered last — registration order usually wins.
• Do not vendor the filter source. If you have previously copied filter implementations into your app to avoid the dependency, the 1.1.0 style pass will make your diff noisy and meaningless. Either depend on the package properly or own the code fully; do not half-fork.
• Debugging tip: assert on the filter name string as well as the output. A surprising number of "the filter did nothing" reports are a typo'd or unregistered name that silently passes the value through unchanged.