Stringservice Laravel Package

Getting Started

The package has no Packagist entry, so composer require loicpennamen/stringservice will fail. You must wire it in as a VCS repository and pin a ref:

{
    "repositories": [
        { "type": "vcs", "url": "https://bitbucket.org/LoicPennamen/stringservice.git" }
    ],
    "require": {
        "loicpennamen/stringservice": "dev-master#<commit-sha>"
    }
}

Pin the commit. dev-master against a single-maintainer Bitbucket repo is an unattended supply-chain risk, and you want reproducible builds.

Where to look first, in this order:

1. composer.json — PSR-4 namespace, PHP constraint, and whether it requires symfony/framework-bundle or symfony/dependency-injection. This single file decides whether you can use it natively or must extract it.
2. src/ — identify the main service class and enumerate its public methods. The description advertises chainable formatting, slugging, truncation and masking; verify those methods exist and behave, do not trust the description.
3. LICENSE — absent or ambiguous licensing blocks adoption outright; you need redistribution rights to fork and vendor.
4. Any *Bundle.php or DependencyInjection/ folder — if present, the package is Symfony-container-coupled and will not boot in Laravel without an adapter.

Then decide the integration shape before writing feature code:

• Library-only (plain classes, no container wiring): wrap the service in a small Laravel service provider and optionally a facade, then use it.
• Symfony bundle: do not attempt to load it. Either write a Laravel service provider that instantiates the underlying string class directly, or copy the two or three methods you actually need into app/Support/.

First use case worth prototyping: a single chained call in a Blade/API response path, e.g. producing a display title from raw user input. That exercises slugging, truncation and multibyte handling in one go and will surface encoding or ellipsis bugs immediately.

// If library-only and bound in a provider:
$slug = app(StringService::class)
    ->of($request->input('title'))
    ->slug()
    ->limit(60)
    ->toString();

Compare that output against Str::slug($title) and Str::limit(...) on the same inputs before committing to the dependency. In most Laravel codebases the framework-native chain is equivalent:

$slug = Str::of($title)->slug()->limit(60, '');

If the outputs match, you have your answer: write the internal helper, skip the dependency.

Implementation Patterns

Wrap, never spread. Bind the service behind an interface you own so upstream classes never leak into controllers, jobs or Blade templates:

namespace App\Support\Text;
 
interface TextFormatter
{
    public function slug(string $value): string;
    public function limit(string $value, int $length, string $end = '…'): string;
    public function mask(string $value, int $visible = 4): string;
}

Implement it with the package internally, register it in a service provider, and resolve the interface everywhere else. When (not if) you fork or replace the package, the swap is one class.

Service provider wiring. For a plain library the provider is trivial; keep it free of Symfony container assumptions:

public function register(): void
{
    $this->app->singleton(TextFormatter::class, fn () => new PackageTextFormatter());
}

Do not register a facade unless the team already has a facade convention — facades hide the dependency and make future replacement harder.

Chain at the boundary, not in the domain. Use the chainable API where presentation is assembled — API resources, view models, mail templates. Do not let fluent string chains become part of model accessors or domain methods, because those chains are the hardest thing to swap out later and the easiest place for an encoding bug to hide.

Normalise once, on input. Masking and truncation are display concerns; sanitising belongs at the request boundary. Put the sanitising calls in a form request or a small SanitisesInput trait, and keep truncation in the resource layer. Mixing them produces double-processed strings where an ellipsis ends up inside a slug.

Pin and vendor via a fork. If you adopt it, fork under your org, add a composer.json "version" or tag scheme, add CI with a PHP-version matrix, and require the fork rather than Bitbucket directly. This removes the availability failure mode where Bitbucket permissions or commit history changes break composer install on a fresh clone in CI.

Keep an attribution block. If you extract methods instead of installing the package, copy the relevant algorithm into app/Support/Text/ with a header noting origin, author and license. This is cheap now and expensive to reconstruct in an audit.

Feature-test against Str. Write a dataset test that runs your adapter and the equivalent Str chain over the same inputs (ASCII, accented Latin, CJK, emoji, empty string, long input) and asserts the intended behaviour. This doubles as your extraction checklist if you later drop the package.

Gotchas and Tips

It is not a Laravel package. The description targets Symfony. Expect symfony/framework-bundle constraints, a bundle class, and possibly a Configuration tree. Laravel does not load Symfony bundles, so the "optional Laravel integration" you might hope for is likely absent. Plan for the adapter or the extraction from the start; do not discover it after a sprint of feature work.

composer why-not before anything. Laravel already pulls Symfony components transitively and pins versions. A package constrained to an old symfony/string or requiring a specific symfony/dependency-injection major can produce a conflict that only appears during a Laravel upgrade, not at install time. Run:

composer why-not loicpennamen/stringservice <your-laravel-version>

and check the resolved Symfony component versions.

Multibyte claims need proof. "Multibyte-safe" in a description is a claim, not a test. Verify mb_* usage and explicit UTF-8 encoding arguments in the source. Common failures: substr instead of mb_substr, strlen for length limits, and ellipsis truncation that counts bytes so a 60-byte limit cuts a 20-character Japanese string. Test masking on multibyte input specifically — masking by byte offset corrupts characters.

Ellipsis behaviour is the usual bug. Check whether the ellipsis is counted inside or outside the truncation limit, and whether truncation happens when the string is exactly the limit. This differs between implementations and will silently change your UI copy widths. Assert it in a test rather than eyeballing it.

Global helper collisions. If the package registers global helper functions (common in Symfony-adjacent utility packages), check for name clashes with Laravel helpers before autoloading. composer dump-autoload will not warn you; a redeclare fatal will appear at runtime on a request that hits the code path.

No support contract. Zero stars, zero dependents, no Packagist metadata, no CVE feed, no visible release cadence. Treat it as vendored source you own. That means: an owning team named in the README, a pinned commit with a comment explaining why, a documented extraction exit plan, and a note in the dependency inventory for license and PHP-version upgrade obligations.

Encoding and locale regressions are silent. If the package touches setlocale, iconv, or transliteration, its output can differ between CI and production containers with different locales installed. Pin locale in tests or avoid the locale-dependent methods entirely.

Restrict it to display paths. Keep it out of auth, payments, persistence and anything with a security-response expectation. Masking utilities in particular look security-adjacent but are cosmetic — never use a masked string as an actual data-protection mechanism, and never let a masked value round-trip into storage.

Extension points are limited. With a single maintainer and no test suite evidenced, do not rely on upstream accepting patches. If you need a behavioural change, make it in your fork or in your adapter, and record the divergence in the README so the next engineer does not assume parity with upstream.

Prefer the exit. The realistic outcome of evaluation is that Illuminate\Support\Str and symfony/string cover the same ground plus correct Unicode handling and active maintenance. Write the 30-line internal helper, own the tests, and revisit only if a concrete documented capability gap appears.