Utilities Laravel Package

Getting Started

1. Install and verify what you actually got

composer require becklyn/utilities

There is no service provider and no config file — this is a plain PSR-4 library of classes. Do not run vendor:publish looking for a UtilitiesServiceProvider; it does not exist. Confirm the install and the resolved version:

composer show becklyn/utilities
ls vendor/becklyn/utilities/src

2. Read the source first, not the docs

The package advertises itself as "classes too small for their own libraries", so src/ is the documentation. The only names confirmed by the release notes are:

• Becklyn\Utilities\Enum — abstract base for enumerated values (1.0.0)
• Becklyn\Utilities\Collection\IterableToCollectionConstructionTrait — build collections from any iterable (1.0.0)

Ignore any blog post or generated summary that lists StringUtils, ArrayUtils, DateTimeUtils, or FileUtils — grep before you use:

grep -rn "class \|trait \|interface " vendor/becklyn/utilities/src

3. First use case: replace a constant class

The highest-value day-one move is swapping a hand-rolled status/type constants file for the Enum base, because it removes an entire category of "is this string valid?" bugs.

use Becklyn\Utilities\Enum;

final class OrderStatus extends Enum
{
    public const PENDING   = 'pending';
    public const PAID      = 'paid';
    public const CANCELLED = 'cancelled';
}

Open vendor/becklyn/utilities/src/Enum.php and check exactly which helpers the base gives you (value listing, validity assertion, construction from a raw value) — the surface changed in 2.0.0 when PHP 8 return types were added, so older examples will not match.

4. Then wire it into a FormRequest

'status' => ['required', Rule::in(OrderStatus::values())],

That single line is usually where the payoff becomes visible to the rest of the team.

Implementation Patterns

Enum as the single source of truth for a domain vocabulary

Keep the constants in one final class and never repeat the string literals. Reach for the base class helpers in the three places they matter:

• Validation — Rule::in(Status::values()) in FormRequests, or an assertValid() call in a service before persisting.
• Presentation — a label() method on your subclass (the base is abstract precisely so you can add domain methods), consumed by Blade/Inertia serializers.
• Persistence — store the raw string; do not cast the Eloquent attribute directly to the Enum class unless you write an Illuminate\Contracts\Database\Eloquent\CastsAttributes adapter, because the base class almost certainly does not implement Castable.

protected $casts = ['status' => OrderStatusCast::class]; // thin wrapper you own

Collection construction from generators

IterableToCollectionConstructionTrait is for the case where you have a Generator or Traversable and want collection semantics without iterator_to_array() materialising an array first.

use Illuminate\Support\Collection;
use Becklyn\Utilities\Collection\IterableToCollectionConstructionTrait;

final class UserCollection extends Collection
{
    use IterableToCollectionConstructionTrait;
}

$users = UserCollection::fromIterable($this->streamUsersFromCursor());
$users->filter(fn (User $u) => $u->isActive())->take(50);

Verify the exact factory method name inside the trait — it is the only public API of the trait and it is trivially greppable. Use this in Artisan commands, CSV/XLSX exporters, and cursor-based report jobs where a Collection would otherwise force a full array load.

Keep a one-class anti-corruption layer

Because this package is a zero-star, single-vendor grab bag, do not let Becklyn\ namespaces leak across your codebase. Wrap each utility you adopt:

namespace App\Support;

final class Statuses
{
    public static function all(): array { return OrderStatus::values(); }
}

Swapping to a native PHP 8.1 enum, or to a fork, then becomes a one-file change instead of a codebase-wide search.

Where it does not fit

• Do not use it as an Arr::/Str:: replacement — Laravel's own helpers are better tested and better documented.
• Do not use it for validation, HTTP, or config concerns; it has no Laravel integration points at all.
• Do not adopt it as a "just in case" utility belt. Adopt individual classes against a named pain point.

Gotchas and Tips

Version constraints bite harder than usual

• 3.0.0 requires PHP ≥ 8.2 and adds Symfony 7.4 support while dropping Symfony 5.4. If you are still on Laravel 9 with Symfony 6.0–6.3 internals, you want the 2.x line.

• The only Illuminate constraint ever mentioned in the changelog is illuminate/collections ^9 (2.0.3). Nothing in the release notes bumps it. Before assuming Laravel 11/12 compatibility for the collection trait, run:

  composer why-not illuminate/collections ^11.0
  

  If it conflicts, you can usually still install with --ignore-platform-reqs-style contortions, but the right answer is: use Enum (framework-agnostic) and skip the collection trait.

Pin the exact version

With zero stars and zero dependents, there is no crowd to discover breakage for you. Pin it literally:

"becklyn/utilities": "3.0.0"

and vendor or fork the two or three classes you actually use if the project is long-lived. The whole point of this package is that the code is small enough to own.

Native enums may already be the better answer

Becklyn\Utilities\Enum predates PHP 8.1. For new code, a native enum Status: string implements HasLabel gives you ::cases(), ::tryFrom(), and first-class Laravel enum casting for free. Choose the Becklyn base class only where you need a non-final class that can be extended, or where you are maintaining an existing codebase that already has dozens of these subclasses.

No service provider means no framework magic — and no facades

Nothing is registered in the container, so there is no Utilities:: facade, no config key, and no about output. Instantiate or call statically. This also means Laravel Telescope and the exception handler will give you nothing useful if a utility throws — reproduce the call in tinker:

php artisan tinker
>>> \Becklyn\Utilities\Enum::class

Static analysis is your test suite

The package ships no public test suite or documented behavioural contract. For every utility you depend on, add a small test that asserts your expectation, not the package's:

it('treats unknown statuses as invalid', function () {
    expect(OrderStatus::isValid('bogus'))->toBeFalse();
});

That test becomes the acceptance criteria for your eventual replacement, whether that is a native enum or a fork.

Debugging

Step into vendor/ with Xdebug — the classes are small enough to read in full in under a minute, which is the fastest debugging tool available here. Set a breakpoint at the top of the class rather than guessing at behaviour from the name.

Extension points are just inheritance

Enum is abstract by design; IterableToCollectionConstructionTrait is a trait. There are no plugin hooks, no events, no config toggles. Your extension points are: subclass the enum, use the trait in your own collection class, or fork. Prefer the first two.