Helpers Laravel Package

Getting Started

1. Install and confirm autoloading

   composer require acacha/helpers
   

   On Laravel 5.5+ the service provider should be auto-discovered. On older versions, register it manually in config/app.php:

   Acacha\Helpers\HelpersServiceProvider::class,
   

2. Look here first, in this order

   • vendor/acacha/helpers/README.md — the canonical list of what is actually exposed.
   • vendor/acacha/helpers/composer.json — check the autoload block. Helper packages almost always ship a "files": [...] entry; that file is the real API surface.
   • vendor/acacha/helpers/src/ — read the service provider before anything else. It tells you whether config is merged, whether Blade directives or macros are registered, and whether anything is published.

3. Publish config if it exists

   php artisan vendor:publish --provider="Acacha\Helpers\HelpersServiceProvider"
   

   Inspect the resulting config/helpers.php (or similarly named file) before writing code against it — defaults are often environment-sensitive.

4. First use case

   The fastest win is replacing a hand-rolled app/helpers.php. Before the package:

   // app/helpers.php
   if (! function_exists('str_slug_es')) { /* ... */ }
   

   After: delete the local copy, composer dump-autoload, and call the package's equivalent directly in a controller or Blade view. Verify with php artisan tinker that the function resolves before deleting anything:

   >>> function_exists('the_helper_name');
   => true
   

Implementation Patterns

Use helpers where they reduce ceremony, not where they hide logic. These packages are collections of small utilities (string/array manipulation, formatting, URL/slug handling, request shortcuts). The natural home is:

• Blade templates — formatting dates, truncating, building class strings.
• Form Requests and controllers — light normalisation before validation.
• Seeders and factories — deterministic data shaping.

Wrap vendor helpers behind your own facade or app-level helpers. This is the single most valuable pattern with a 25-star package. Create app/Support/Helpers.php or a App\Helpers class that delegates:

namespace App\Support;

class Text
{
    public static function slug(string $value): string
    {
        return \the_package_helper($value); // single point of change
    }
}

When the package is abandoned or a function is renamed, you edit one file instead of grepping the codebase.

Prefer class-based usage over global functions when available. If the package exposes namespaced classes (e.g. Acacha\Helpers\...), inject or use them. Static/global functions are convenient but invisible to static analysis and IDE autocompletion.

Integrate through a project-level service provider. Register any package macros, Blade directives, or config defaults in your own AppServiceProvider rather than editing vendor code:

public function boot()
{
    // e.g. Blade::directive(...) built on top of package helpers
}

Testing pattern. Because helpers are global functions, they are trivially testable but also trivially polluted. Add a small test that asserts the helpers you depend on are loaded — this catches the "worked locally, broke in CI" autoload class of bug:

public function test_helpers_are_autoloaded(): void
{
    $this->assertTrue(function_exists('the_helper_name'));
}

For anything with branching logic, test through your wrapper (App\Support\Text::slug()) so tests survive a package swap.

Composer wiring. If you are on a legacy project with a manually maintained app/helpers.php, add the package's file to your composer.json only if auto-discovery/files autoload is not already handling it — double-loading the same functions causes fatal redeclare errors.

Gotchas and Tips

Global namespace collisions are the number one failure mode. Many helper packages guard definitions with if (! function_exists(...)). That guard is a coin flip: it either silently lets your definition win (confusing debugging) or causes a hard Cannot redeclare fatal. Before adopting, grep your own app/ for the function names the package defines:

grep -rn "function helper_name" app/ 

autoload.files is loaded once per process — and cached. After composer require, always run:

composer dump-autoload
php artisan config:clear
php artisan cache:clear

If a helper "doesn't exist" in a queued job or an Octane worker but works in a request, suspect stale autoload state, not the package.

Config caching will freeze published config. If you publish a config file and later change it, php artisan config:cache must be re-run in every environment. In CI, a cached config from a previous step is a classic source of "works on my machine."

Auto-discovery assumptions. If the provider is not in bootstrap/providers.php (Laravel 11+) or config/app.php (older), composer dump-autoload will not fix it. Check php artisan about or:

>>> app()->getLoadedProviders()

and confirm the package's provider appears.

Low-maintenance package risk. 25 stars and a low opportunity score means: no guarantee of Laravel-version compatibility, no guarantee of PHP 8.3+ typing, and possible abandonment. Practical mitigations:

• Pin a version range you have actually tested ("acacha/helpers": "^1.0"), and commit composer.lock.
• Treat helper output as untrusted for anything security-relevant (slugs used in routing, HTML escaping in Blade). {{ }} still escapes; never use it with {!! !!} on helper output you have not audited.
• Read the source of any helper whose behaviour you rely on — these files are small, and behaviour like transliteration, Str-vs-mb_* usage, or whitespace trimming often differs subtly from what the name implies.

Debugging checklist when a helper misbehaves

// Which file defined it?
$ref = new ReflectionFunction('helper_name');
dump($ref->getFileName(), $ref->getStartLine());

// Is it shadowed by your own app/helpers.php?
dump(function_exists('helper_name'));

ReflectionFunction immediately distinguishes "package is broken" from "your bootstrap defines the same name."

Extension points to prefer. Rather than forking, use: (a) your own wrapper classes, (b) Laravel's Str/Arr/Collection macros registered in a service provider, and (c) Blade directives. Reserve forking for a genuine bug, and if you fork, note it in the README — the next developer will otherwise assume upstream behaviour.

Migration escape hatch. If the package is abandoned, the exit is mechanical: copy the handful of functions you actually call into app/Support/, keep your wrapper signatures identical, drop the dependency, and run the "helpers are autoloaded" test suite to prove nothing broke. Designing for that exit from day one is the correct posture for a small, single-maintainer helper library.