Symfony Toolbox Bundle Laravel Package

Getting Started

1. Pull the new release: composer update vendor/package (or composer require vendor/package:^1.1 for a fresh install). No migration or config publish step is implied by 1.1.4.
2. Confirm the version actually landed with composer show vendor/package — the Dockerfile and dev/debug tooling only reach your project through the vendor update, not through a separate install.
3. Look first at src/StringTools.php (or the equivalent StringTools class/helper file) and diff it against 1.1.3: git diff 1.1.3..1.1.4 -- vendor/package. The three new formatters are additive, so the diff is the fastest way to learn their exact names and signatures.
4. First use case: take an existing ad-hoc formatting call in a model accessor or Blade view and replace it with the new formatter, e.g. StringTools::formatX($value) inside getDisplayNameAttribute(). Run the existing test suite immediately afterwards to confirm output parity with whatever you were doing before.

For the Docker side, the new Dockerfile and debug tooling are for contributing to or debugging the package itself, not for your application runtime. Read the Dockerfile before using it, and treat it as a reference implementation of the package's expected PHP/extensions rather than something to drop into your app's compose stack.

Implementation Patterns

Formatter usage in the domain layer. The natural home for the new StringTools formatters is model accessors, cast classes, and form requests — anywhere you already normalise user-supplied strings. Prefer calling them in one place (an accessor or a small dedicated presenter) over sprinkling calls across controllers and Blade, so a future formatter behaviour change is a one-line fix.

Compose with the existing helpers. Formatters are most useful chained after trim/Str::of() normalisation. Establish a house order — trim, then collapse whitespace, then format — and apply it consistently; otherwise the same input can produce different output depending on which code path it enters.

Blade and API resources. For display-only formatting, call the formatter in the Blade partial or API Resource rather than persisting the formatted value. Keep the raw column untouched so you can re-run formatting later when the formatter is fixed or extended.

Docker for local debugging. Use the shipped Dockerfile to reproduce a bug against the package in isolation — mount your failing input as a fixture, step through with Xdebug, and confirm whether the issue is in the formatter or in your calling code. This is materially faster than debugging through a full Laravel app with a queue worker and HTTP stack in the way.

Testing. Add a data-provider test per formatter covering: empty string, null (if accepted), multibyte/UTF-8 input, and already-formatted input (idempotency). These four cases catch nearly every formatter regression, and they make the upgrade to 1.1.5 trivial to validate.

Pin and document. Since formatters directly affect user-visible output, note the package version in your composer.json constraint and add a changelog entry when you upgrade — reviewers should know a display change came from a dependency bump, not from application logic.

Gotchas and Tips

• Don't ship the Dockerfile to production. It's dev/debug tooling and may include Xdebug, relaxed PHP settings, or a non-production base image. Check it isn't being copied into your deployment artefacts if you vendor the package into a build context.
• Debug tooling has a runtime cost. If the new debug helpers register listeners, middleware, or dump handlers, confirm they're gated behind an environment check or config flag. Benchmark a hot path before and after if you enable them in a shared staging environment.
• Additive ≠ behaviour-neutral. Three "new" formatters can still change existing output if they share private helpers with the old ones. After upgrading, snapshot-test any user-facing string produced via StringTools.
• Encoding is the usual culprit. Multibyte input (accents, emoji, CJK) is where formatters break first. Test with real production-shaped data, not "hello world".
• Null and empty handling is inconsistent across formatters by nature. Decide explicitly whether your accessor should return null or '' and wrap the call accordingly rather than relying on the formatter's default.
• Idempotency is not guaranteed. Running a formatter twice may not equal running it once. Never format on both write and read paths.
• Extending rather than forking. If you need a variant, wrap the formatter in your own helper class instead of editing vendor code — a fork will silently revert on the next composer update and you'll debug it twice.
• Debugging upgrade issues: if output changes after the bump, git log 1.1.3..1.1.4 in the vendor directory and read the formatter diff first; most "random" formatting regressions are a one-line change in a shared private method.