Ecow Laravel Package

Getting Started

inmanturbo/ecow is a small, single-purpose Eloquent helper package — one composer require and you're in. There's no build step, no published assets, and (based on the release history) no meaningful config surface to learn before you can use it.

composer require inmanturbo/ecow

Where to look first:

1. vendor/inmanturbo/ecow/src/ — the whole package is only a handful of files. Read the entry point (helper functions / trait / class) top to bottom; it will take five minutes.
2. vendor/inmanturbo/ecow/tests/ — for a package this small the test suite is the real documentation. It shows the exact supported argument shapes and return values far more reliably than the README.
3. composer.json → require block — confirm the PHP and illuminate/* constraints match your app before you get attached to it.

First use case: optional model resolution. The natural fit is anywhere a lookup can legitimately come back empty — nullable foreign keys, optional belongsTo relations, "edit if it exists, create if it doesn't" flows, or API endpoints where a missing record is a 404 rather than an exception. As of v1.0.4, a lookup that finds nothing returns null instead of surfacing a model-not-found error, so it drops cleanly into nullsafe chains:

$model = ecow(SomeModel::class)->find($id);

return $model
    ? new SomeResource($model)
    : response()->noContent();

Start there, then look for findOrFail-style calls you've been wrapping in try/catch — those are the candidates this package replaces.

Implementation Patterns

Wrap it, don't sprinkle it. Even though it's a one-liner, put the call behind a method on your repository/action class (findOrNull()), so when the package's semantics shift again — and they shifted once already in a patch release — you have a single edit site.

Use it for the "absence is normal" branch only. Keep findOrFail/route-model-binding for the paths where a missing model genuinely is an error (a 404 out of Route::get('/posts/{post}') is correct behaviour). Use ecow where the caller is expected to branch on null.

Nullsafe everything downstream. The idiomatic post-1.0.4 shape is:

$user = ecow(User::class)->find($id);

$name = $user?->profile?->display_name ?? 'Guest';
$count = $user?->orders()->count() ?? 0;

Restore fail-fast where you want it. If you preferred the pre-1.0.4 behaviour, make it explicit rather than relying on the package:

$model = ecow(SomeModel::class)->find($id)
    ?? throw (new ModelNotFoundException)->setModel(SomeModel::class, [$id]);

API layer pattern. Resolve with ecow inside a form request or a small action, then translate null into whatever your API contract wants — 404, 204, or an empty resource — in one place. Don't let the null leak into controllers that assume a model.

Test both branches explicitly. After the v1.0.4 change, add a test asserting the empty case returns null. It documents the contract for future upgraders and catches a revert.

Compose with existing Eloquent, don't fight it. Anything you can chain on a builder you can generally chain here; if the package returns a builder-ish object, use it as a starting point and add where() clauses before resolving.

Gotchas and Tips

v1.0.4 is a semantic change in a patch release. "Return null if no model" means the previous contract — whatever form of failure it was — no longer applies. Before you upgrade:

• Grep for catch (ModelNotFoundException and catch (Throwable around ecow calls. Those handlers are now dead code.
• Grep for direct property access on the result ($result->id, $result->name). Unguarded accesses that used to throw a domain exception now throw Error: Attempt to read property on null — a different, uglier failure at a different place.
• Run Larastan/PHPStan at a decent level after upgrading. With a now-nullable return, static analysis is the fastest way to enumerate every unguarded call site.

Pin the version if you can't migrate today. "inmanturbo/ecow": "1.0.3" in composer.json buys you time; a composer update in CI will otherwise silently move you.

Null results are usually a query problem, not a package problem. If you get null for a row you can see in the database, the culprit is almost always a global scope (SoftDeletes, multi-tenancy, published/draft scopes) or a stale where clause. Debug with DB::listen(fn ($q) => dump($q->sql, $q->bindings)) around the call, or temporarily ->withoutGlobalScopes() to confirm.

Config caching. If the package exposes any config, remember php artisan config:cache in deploys — a cached config in bootstrap/cache will mask your local edits and produce "why is it behaving differently on staging" afternoons.

Extension points are thin, by design. For a package this small, don't wait for an official hook — bind your own resolver in a service provider or wrap the helper in your own class. That wrapper is also your escape hatch if the package goes unmaintained.

Low maintenance risk, thin docs. One author, tiny surface area, one PR per release. That's fine for what it does, but it means the README may lag the code: trust src/ and tests/ over the docs, and read the changelog before every minor bump rather than assuming semver purity.