Helpers Laravel Package

Getting Started

Install it as a normal dependency and confirm which PHP line you need — the releases are branched per elasticMS major (6.9.x for older PHP, 7.x for the current line), so pick the branch matching your runtime before composer require elasticms/helpers.

composer require elasticms/helpers:^7.0
composer dump-autoload   # some helpers are plain namespaced functions in "files" autoload

Where to look first, in this order:

1. vendor/elasticms/helpers/src/ — the real API. The README is a stub; the source tree is the documentation. Namespaces are grouped by concern (Standard\Json, Standard\Type, File\..., array/text utilities), so ls -R gives you the catalogue in ten seconds.
2. vendor/elasticms/helpers/tests/ — when published, the tests are the best usage examples: they show exactly what each wrapper returns and what it throws.
3. The online docs at ems-project.github.io/#/dev/helpers/index.md — useful for intent, but always verify signatures against the installed version.

First use case, and the one that pays off fastest: a boundary. Take a controller, import command, or queue job where you currently receive mixed and immediately json_decode() it. Replace that with the package's typed decode and type coercion wrappers so PHPStan knows the shape from that point on:

use EMS\Helpers\Standard\Json;
use EMS\Helpers\Standard\Type;

$payload = Json::decode(Type::string($request->getContent())); // array, not mixed
$id      = Type::integer($payload['id'] ?? null);              // int, or throws

That single change usually removes a cluster of @phpstan-ignore lines and mixed-type cascade errors downstream.

Implementation Patterns

Coerce at the edges, never in the core. The package's value proposition is that a wrapper returns a precise type or throws. Use them in form requests, console command option parsing, config readers, and API clients; keep domain/services fully typed and free of helpers. If you find yourself calling Type::string() on an already-typed variable, the coercion is in the wrong layer.

Treat wrappers as an alternative to the PHPStan baseline, not an addition to it. Adoption pattern that works:

1. Run PHPStan at your target level with a baseline.
2. Pick the top offending files (phpstan analyse --error-format=json then sort by file).
3. Replace native calls with the typed wrappers there.
4. Delete the corresponding baseline entries, raise the level, repeat.

Each deleted baseline line is a permanent win; a growing baseline is a permanent tax.

Wrap once, expose your own façade. Because the package is low-traffic and versioned with the elasticMS monorepo, don't sprinkle EMS\Helpers\... across hundreds of files. Put a thin App\Support\Typed (or extend Laravel's Str/Arr usage) that delegates to the helpers for the handful you actually use. Swapping or forking later becomes a one-file change, and your IDE autocompletes your own vocabulary.

Integrate with Laravel's typed boundaries. Custom casts, DTO fromArray() constructors, and resource classes are natural homes:

final class Money
{
    public static function fromArray(array $data): self
    {
        return new self(Type::integer($data['amount']), Type::string($data['currency']));
    }
}

Use it in tests deliberately. Assert that malformed input throws rather than silently returns false/null — this pins the behaviour you're relying on and protects you when you bump the package.

JSON/YAML/file wrappers in importers and fixtures. Seeder and import pipelines benefit most: Json::encode() returning a guaranteed string removes the string|false branch that otherwise infects every caller.

Gotchas and Tips

• Throwing replaces falsy returns. Native json_decode() returns null, file_get_contents() returns false. The wrappers typically throw. That's the point — but it is a behaviour change in production. Add try/catch at the boundary, map to a 422/500, and make sure error paths have test coverage before you swap call sites in bulk.
• Catch the right exception class. Read the wrapper's @throws and catch that specific type. A broad \Throwable catch will swallow genuine bugs and defeat the purpose.
• Function-style helpers need an autoload dump. If the package ships namespaced functions via the files autoload key, they won't exist until composer dump-autoload runs. This bites in Docker builds that cache an old autoloader and in preloaded/opcache setups.
• No service provider, no config, no facade. It's framework-agnostic pure PHP. Don't go looking for config/helpers.php — none exists, and nothing registers itself in Laravel.
• Version pinning matters more than usual. 0 stars and no dependents means no community buffer. Pin an exact minor ("elasticms/helpers": "7.3.9"), read the changelog entries touching the helpers you use, and avoid depending on undocumented edge behaviour. Fork or vendoring is a legitimate hedge if a wrapper becomes load-bearing.
• PHPStan only helps if types propagate. Don't do Type::string($x) and then pass it into an untyped array or assign it to a mixed property — you've paid the runtime cost and thrown the analysis benefit away. Keep declare(strict_types=1) in files that use them.
• Name collisions in your head, not in PHP. These are not Laravel's Str::/Arr:: helpers and don't mirror their semantics (e.g. multi-byte assumptions, null handling). Pick one idiom per concern per file; mixing both in a single class is where subtle bugs live.
• Overhead is small but not free. The wrappers add a call plus a type check. Fine at boundaries; if you're wrapping tens of thousands of calls inside a tight loop (bulk import per-row JSON parsing), hoist the wrapper outside the loop or use it once per batch.
• Debugging triage. If a wrapper throws where native code returned false, dump the raw value with var_dump(get_debug_type($value)) before the call — the exception messages describe the expected type, and the most common cause is a value arriving as int where you assumed string (form input, database driver casts, decoded JSON numbers).
• Extension point is composition. There is no plugin API. The supported way to add a helper is your own façade class calling the package's wrappers, which also keeps you insulated from upstream churn.