Laravel Helpers Laravel Package

Getting Started

The package gives you a managed way to organize, load, and validate PHP helper files (the kind of free functions you'd normally dump in app/helpers.php) instead of relying on Composer files autoloading.

1. Requirements check first. v3.0.0 requires PHP ^8.3. Confirm your runtime and CI matrix before upgrading — this is the most likely thing to block you.
2. Install and publish config:

   composer require devtical/laravel-helpers
   php artisan vendor:publish --tag=helpers-config
   

   Note the tag is now helpers-config (see Gotchas — old scripts using a different tag will silently publish nothing).
3. Look at config/helpers.php first. This is where you declare which helper files get loaded, and where the new log_errors and strict options live.
4. Create your first helper:

   php artisan make:helper formatting
   

   The refactored stub now includes declare(strict_types=1), so generated files are strict-typed by default.
5. Verify it loaded:

   php artisan helper:list
   

   In v3 this shows a per-file function count and a failed status, so it doubles as your first debugging tool.

Your first realistic use case: pull a growing app/helpers.php into a few domain-specific files (e.g. formatting, arrays, urls) and let the manager handle loading order and failure reporting.

Implementation Patterns

Domain-partitioned helper files. Rather than one giant helpers file, create one per concern with make:helper and register each in config. This keeps helper:list output meaningful (function counts per file) and limits blast radius when one file has a syntax error.

CI validation gate. Add the new command to your pipeline:

php artisan helper:validate

It does syntax checks and duplicate function detection — the latter is the killer feature for teams where two people both add a format_money() helper in different files. Fail the build on non-zero exit.

Dev-time reload loop. While iterating on helper files:

php artisan helper:reload

Use this instead of bouncing php artisan serve or config:clear repeatedly. Treat it as a local-only convenience — don't wire it into deploy scripts.

Tooling/introspection via JSON. helper:list --json gives you structured output (function counts, failed status). Good for:

• A small custom artisan command or dashboard that flags files with zero functions (dead helpers).
• Pre-deploy sanity scripts that assert no file is in a failed state.

Surface load failures instead of swallowing them. With log_errors enabled, HelperManager logs failed helper file loads. In non-production environments keep this on so a broken helper file shows up in laravel.log rather than just silently missing a function at runtime. In production, decide deliberately: logging is useful for diagnosis, but a missing helper function often surfaces first as a confusing Call to undefined function elsewhere.

Strict types as a default, not an accident. Because the stub now emits declare(strict_types=1), new helpers enforce strict argument types. Adopt this consistently — mixing strict and non-strict helper files makes argument coercion behavior surprising to debug.

Package-tools conventions. The service provider now uses spatie/laravel-package-tools. If you were extending or overriding the old provider, expect the registration mechanics to have shifted (config merge, command registration, publishable assets are now declared via Package:: calls). Anything that reached into provider internals needs a review.

Gotchas and Tips

• Breaking: publish tag renamed. --tag=helpers-config is now required. Any provisioning script, Dockerfile, or composer post-install hook using the old tag will exit 0 while publishing nothing — a silent failure that manifests later as "config options have no effect." Grep your repo and infra for the old tag.
• PHP 8.3 floor. If you support multiple PHP versions, the upgrade forces a runtime bump. Check composer.json require.php, any Docker base images, and CI matrices together.
• strict config option can change runtime behavior. Enabling it (or inheriting strict behavior from the new stubs) surfaces type errors that non-strict code silently coerced. Roll it out to staging first and watch for TypeErrors in helpers that previously "just worked."
• declare(strict_types=1) in generated stubs is a per-file contract. Strictness is determined by the calling file for scalar coercion, but the declaration in helper files ensures their own internal signatures are strict. Don't copy-paste old non-strict helpers in and assume parity.
• Failed loads may be invisible if log_errors is off. If a helper function is mysteriously undefined, first run helper:list and check for failed status, then confirm log_errors is enabled before digging through logs.
• helper:validate catches duplicates, not conflicts with other packages. Two helpers with the same name across your files are detected; collisions with functions from third-party packages or PHP extensions are not.
• helper:reload is a development tool. Don't assume it's safe or meaningful in a long-running production worker (Octane, queues) — those processes hold their own opcache/state.
• JSON output is your integration contract. If you script against helper:list --json, pin expectations to the field names — treat them as a semi-public API and re-check after future minors.
• Debugging order when something's wrong: helper:list (failed status + counts) → helper:validate (syntax + dupes) → check log_errors is on and inspect laravel.log → confirm the file is actually listed in config.
• Extension points: the HelperManager now tracks failures — if you're building custom tooling, that failure state is the most useful hook to surface in your own commands/dashboards rather than re-parsing files yourself.