Toolbelt Laravel Package

Getting Started

lsrur/toolbelt is a thin Laravel wrapper around a set of standalone PHP helper functions. The value proposition is narrow but real: functions that would otherwise live in a helpers.php you copy between projects, packaged so they load automatically and can be overridden per-app.

Install

composer require lsrur/toolbelt

Because it targets Laravel, expect package auto-discovery to register the service provider (no manual config/app.php entry needed on Laravel 5.5+). Verify by checking the package's composer.json for both:

• extra.laravel.providers — the service provider
• autoload.files — a helpers.php-style file, which is how global functions actually get loaded

Where to look first

1. composer.json in the package — confirms whether functions are loaded via autoload.files (global namespace) or exposed through a facade/class. This determines your entire usage style.
2. The src/ directory — the helper file is usually src/helpers.php, src/Support/helpers.php, or split by domain (arrays, strings, URLs, numbers).
3. Any config/toolbelt.php — if present, publish it with php artisan vendor:publish --provider="Lsrur\Toolbelt\ToolbeltServiceProvider" and read every key. Config is where per-app behaviour (defaults, formatting, locale) will be tunable.

First use case

Do not adopt this package wholesale. Inventory the helpers first:

# If functions are globally autoloaded, list them
grep -rE '^\s*function ' vendor/lsrur/toolbelt/src/

Then pick the one or two functions that genuinely save you code in your current app — typically array/string/path manipulation that Laravel's Str/Arr doesn't cover. Write a one-line tinker check:

php artisan tinker
>>> some_toolbelt_function('input');

If that works, you're integrated. If not, the provider or autoload file isn't loading — which is the single most common first-run failure.

Implementation Patterns

Direct global calls (default pattern)

With autoload.files, functions are available everywhere with no import — controllers, jobs, Blade, Artisan commands, tests. This is the intended usage:

// app/Http/Controllers/ReportController.php
public function show(Report $report)
{
    return view('reports.show', [
        'summary' => toolbelt_summary($report->lines), // whatever the helper is called
    ]);
}

Wrap, don't scatter

Treat the package as an implementation detail, not a public API. In anything you expect to maintain for more than a few months, wrap the calls in domain-level helpers or a small service:

// app/Support/Format.php
namespace App\Support;

class Format
{
    public static function money($amount): string
    {
        return toolbelt_currency($amount, config('shop.currency'));
    }
}

Now a package swap, a bug in the helper, or a change in business rules touches one file instead of fifty. This also gives you a seam for tests.

Blade usage

Global functions are fine in templates, but keep them dumb — formatting only, no queries, no side effects:

{{ toolbelt_excerpt($post->body, 120) }}

If a helper is doing anything more than pure formatting, move it behind a view model or accessor instead.

Replace local app/helpers.php with a curated subset

The strongest real-world pattern: if your app already has app/helpers.php, diff it against this package. Delete the duplicates, keep yours for domain logic, and let the package cover the generic utilities. Register yours the same way in composer.json:

"autoload": {
    "files": ["app/helpers.php"]
}

Run composer dump-autoload after any change to autoload.files.

Testing

Because these are pure functions, they're cheap to lock down. If a helper's behaviour matters to your domain, add a small test asserting the contract you depend on — that way a dependency bump that silently changes behaviour fails your suite, not production:

public function test_currency_format_is_stable(): void
{
    $this->assertSame('$1,234.50', toolbelt_currency(1234.5, 'USD'));
}

Compose with Laravel instead of reinventing

Use the package alongside Str/Arr, not in place of them. Reach for Str::of(), Arr::get(), Number::format() (Laravel 11+) first; use toolbelt only for the gap. Keep the mental model: Laravel core = first choice, toolbelt = supplement.

Gotchas and Tips

Global function collisions are the main risk. Two packages can define the same function name, and PHP fatals at load time with "Cannot redeclare." Check the package's helper definitions for function_exists() guards — good helper packages have them, but you cannot rely on it. Mitigations:

• Audit the function names once during install (the grep above).
• If you hit a collision, define the function in your app's helpers.php first, or drop the offending package.
• Never add this package to a project that vendors large helper-heavy packages (e.g. multiple *-helpers libraries) without checking names first.

autoload.files has no lazy loading. Every helper file is parsed on every request, in every context — web, queue worker, Artisan, PHPUnit. For a small package this is negligible, but with OPcache on and opcache.validate_timestamps tuned, confirm you're not re-parsing on each request in production. It also means you cannot tree-shake: you pay for all functions whether or not you use them.

No IDE autocompletion. Global functions aren't discoverable by PhpStorm or Psalm/PHPStan. Address this with a generated _ide_helper.php (barryvdh/laravel-ide-helper) or your own stub file with @method-style docblocks. For static analysis, PHPStan will report unknown functions unless you add stubs or include the package's source in scanFiles.

Config publishing is not idempotent-safe. If config/toolbelt.php exists, re-publishing can overwrite local customisations. Copy the config manually, or run publish with --force only when you've diffed first. Always commit the published config.

Watch the maintenance signal. The package shows zero dependents and no star traction — treat it as unmaintained until proven otherwise. Practical consequences:

• Pin the version in composer.json ("lsrur/toolbelt": "^1.0" with a known-good minor) rather than floating.
• If any helper becomes load-bearing, copy it into app/helpers.php and drop the dependency. Pure functions are trivially portable — that's the escape hatch.
• Don't build a facade or public API on top of it that leaks package-specific names.

Debugging load failures. If a function is undefined despite composer require succeeding:

composer dump-autoload -o
php artisan package:discover
php -r "require 'vendor/autoload.php'; var_dump(function_exists('your_helper'));"

That last one isolates Composer/autoload problems from Laravel boot problems. If function_exists is false there, the package isn't autoloading files at all — inspect its composer.json.

Extension points. The realistic ones are (a) your own wrapper layer, (b) a published config file, and (c) replacing a helper by defining an equivalent function in your app's helpers file before the package loads. There is unlikely to be a container binding or interface to swap implementations — don't design around one. Assume you extend by wrapping, not by substituting.

Namespace hygiene inside the package. If helpers are declared inside a namespace (rather than global), you'll need use function Lsrur\Toolbelt\...; at the top of every file — easy to forget and the cause of "undefined function" confusion. Confirm this in the source before writing code against it.