Laravel Namespaced Helpers Laravel Package

Getting Started

1. Install it with Composer.

   composer require revolution/laravel-namespaced-helpers
   

   There is no service provider to register and no config file to publish. The helpers are loaded through Composer's autoload.files entry, so a plain composer require is all the wiring you need. If you are on Laravel with package auto-discovery, nothing extra is required; if you are outside a booted framework, the autoload still applies as long as vendor/autoload.php is required.

2. Read the source before you use it. This is the single most important first step and it should take well under an hour. Because the package has zero stars, zero dependents, and no published documentation beyond the README, treat the code itself as the spec. Open:

   • vendor/revolution/laravel-namespaced-helpers/composer.json — check the autoload.files entry and the require block (especially the illuminate/support and PHP version constraints).
   • The autoloaded helper file itself — confirm the exact namespace (typically Revolution\LaravelHelpers) and the exact set of functions you actually get. Do not assume the full set of Laravel global helpers are mirrored; assume only what you can see.

   Grep for the specific helper you intend to use — str, collect, data_get, tap, optional — and verify it exists, how it delegates (wrapper vs reimplementation), and how it handles container-dependent helpers like config() or __().

3. First use case: import helpers like you import classes. The entire point is escaping the global namespace so you can use use function imports and get static analysis and IDE navigation:

   use function Revolution\LaravelHelpers\collect;
   use function Revolution\LaravelHelpers\data_get;
   
   $names = collect($users)->pluck('name');
   $city  = data_get($user, 'address.city', 'unknown');
   

   Reach for it the moment you want to import a helper explicitly rather than lean on Laravel's implicit global fallback.

Implementation Patterns

• Always import explicitly with use function. Never call the namespaced functions by fully qualifying them inline unless you have a single occurrence. Explicit imports make dependencies visible, keep grep results meaningful, and give IDEs a jump target instead of a Laravel stub. This is the discipline the package exists to reward — enforce it through code review or a CS-Fixer rule.

• Alias to migrate a file incrementally. You do not need to rewrite an entire file at once. Import under the global name to shadow it for the rest of the file:

  use function Revolution\LaravelHelpers\collect;
  // every subsequent collect() call in this file resolves to the namespaced version
  

  This is the lowest-friction conversion path and, conveniently, gives you clean per-file revertability.

• Use it most aggressively inside your own packages. This is the strongest day-to-day fit for the package. A library that ships its own helpers should not rely on Laravel's global fallback when it may also be consumed outside a full application (with illuminate/support standalone). Namespaced imports make the contract explicit for downstream consumers — who cannot be expected to have every helper you rely on available globally.

• Adopt it in bounded modules, not everywhere. The pattern that works: pick one module or namespace, convert only that module's helper calls, leave the rest of the codebase on globals. Because nothing global is patched, rollback is a composer remove plus a revert of the converted files — no data migration, no runtime config, no deploy-order dependency. Preserve that property.

• Wrap behind an adapter when you need testability. If you need to stub helper behaviour in tests rather than rely on real implementations, inject a small adapter object instead of scattering use function calls across dozens of classes:

  final class Helpers
  {
      public function collect(iterable $items): \Illuminate\Support\Collection
      {
          return \Revolution\LaravelHelpers\collect($items);
      }
  }
  

  This confines the package to a single seam and gives you one place to swap implementations if you fork or replace the dependency.

• Configure your static analysis and linter to recognise the resolution. Run Pint and PHPStan/Larastan over the converted module and verify they resolve the namespaced functions correctly. PHP-CS-Fixer's native_function_invocation rule plus use function imports covers most of the same hygiene without the dependency — if you are already running those tools, add the package alongside them and confirm the combination is coherent.

Gotchas and Tips

• Function resolution is subtle and easy to misread. PHP resolves unqualified function calls in a namespace by falling back to the global function, so namespaced helpers win only inside files that opt in. If a file lacks the use function import, it silently gets the global helper. A reader at the call site cannot tell str() is global or namespaced — and static analysis may not flag the mismatch if it resolves against the global signature. Make the import mandatory and visible in review.

• Beware of shadowing surprises. Aliasing a namespaced collect to global collect in one file while another file in the same class hierarchy uses the global is a debugging trap. Prefer consistent per-directory convention over per-file improvisation.

• Container-dependent helpers can fail outside a booted app. config(), __(), app(), and friends require the container to be up. If the package wraps or reimplements these, verify their behaviour in your test suite under the real bootstrap, not just in unit tests with a mock container. Where they delegate straight to Illuminate\Support behaviour, you also inherit any drift.

• Watch for redeclaration errors. Namespaced functions are not automatically guarded against collision. If another dependency declares functions in the same namespace, or if you fork the package into your own namespace with overlapping names, you get a fatal error. Give your fork a distinct internal namespace.

• Check the framework version constraint, not just the major. illuminate/support is version-locked to the framework and is the most common source of Composer resolver failures on Laravel package installs. Validate against the exact Laravel minor in production, not just the major, and check the tested PHP version against your platform baseline — a package pinned to an EOL PHP minor is a non-starter regardless of merit.

• Assume no upstream maintenance. Zero stars, zero dependents, a single maintainer, no visible release cadence, no security policy. Budget a recurring review each Laravel major to reconcile helper behaviour — helper signatures and behaviour change across major versions, and a shim will lag. If any helper you depend on diverges, fork the file into your own namespace and pin it; the surface area is small enough that owning it is a modest line item rather than a burden.

• Plan the exit before you adopt. Record the decision (an ADR naming the team that owns it and why the convention exists), and document the escape hatch back to global helpers. Without that, the convention becomes folklore new hires cannot reason about — and the cognitive cost of the resolution rule grows with team size and codebase age, not with traffic.