Helpers Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ems-project/helpers
   

   Add to composer.json under require-dev if using for PHPStan compliance only.

2. First Use Case: Replace loose PHP functions with type-safe alternatives. For example:

   use Ems\Helpers\ArrayHelper;
   
   // Before (loose)
   $exists = isset($array['key']);
   
   // After (type-safe)
   $exists = ArrayHelper::has($array, 'key');
   

3. Where to Look First:

   • Documentation for function lists.
   • Ems\Helpers namespace for core helpers (e.g., ArrayHelper, StringHelper).
   • phpstan.neon (if provided) for compliance rules.

Implementation Patterns

Core Workflows

1. Type-Safe Array Operations:

   // Safe access with default
   $value = ArrayHelper::get($array, 'nested.key', 'default');
   
   // Safe merge (avoids type warnings)
   $merged = ArrayHelper::merge($array1, $array2);
   

2. String Manipulation:

   // Slugify with custom rules
   $slug = StringHelper::slugify('Hello World!', '-', ['!']);
   
   // Pluralize/singularize
   $plural = StringHelper::pluralize('user');
   

3. Collection Utilities:

   // Group by with type hints
   $grouped = CollectionHelper::groupBy($items, fn($item) => $item->category);
   
   // Filter with callbacks
   $filtered = CollectionHelper::filter($items, fn($item) => $item->active);
   

4. Integration with Laravel:

   • Service Providers: Bind helpers to Laravel’s container for global access:

     $this->app->bind('arrayHelper', fn() => new ArrayHelper());
     

   • Facade: Create a facade (e.g., Helper) to wrap multiple helpers:

     class HelperFacade extends Facade {
         protected static function getFacadeAccessor() { return 'helpers'; }
     }
     

5. Custom Helpers: Extend existing helpers or create new ones by implementing the HelperInterface:

   class MyHelper extends AbstractHelper {
       public function customMethod(mixed $input): string {
           return (string) $input;
       }
   }
   

Gotchas and Tips

Pitfalls

1. PHPStan Overhead:

   • The package enforces strict typing. Loose PHP functions (e.g., array_key_exists) may trigger errors.
   • Fix: Use the provided wrappers (e.g., ArrayHelper::has()).

2. Performance:

   • Some wrappers add minor overhead (e.g., type checks). Benchmark critical paths.
   • Tip: Cache results for expensive operations (e.g., StringHelper::slugify).

3. Namespace Collisions:

   • Avoid naming conflicts by aliasing helpers:

     use Ems\Helpers\ArrayHelper as EmsArrayHelper;
     

4. Deprecation:

   • The package is actively maintained (last release: 2026), but check changelogs for breaking changes (e.g., 7.0.0 may have BC breaks).

Debugging Tips

1. PHPStan Errors:

   • Run phpstan analyse with --level=max to catch all compliance issues.
   • Use @phpstan-ignore-next-line sparingly; prefer refactoring to wrappers.

2. Dynamic Function Calls:

   • Avoid call_user_func() with helpers unless you’re certain about argument types.

3. Custom Rules:

   • Extend PHPStan’s rules.neon to add custom rules for your helper methods:

     includes:
         - vendor/ems-project/helpers/phpstan.neon
     

Extension Points

1. Add New Helpers:

   • Follow the AbstractHelper pattern. Example:

     class DateHelper extends AbstractHelper {
         public function parse(string $date, string $format = 'Y-m-d'): ?DateTime {
             return DateTime::createFromFormat($format, $date);
         }
     }
     

2. Override Defaults:

   • Publish the package’s config (if any) and customize:

     php artisan vendor:publish --tag=helpers-config
     

3. Testing:

   • Use Ems\Helpers\TestHelper for assertions:

     TestHelper::assertArrayHas($array, ['key']);
     

4. Laravel-Specific:

   • Integrate with Laravel’s Str, Arr, or Collection by creating proxy methods:

     class LaravelHelper extends AbstractHelper {
         public function laravelStr(string $input): string {
             return Str::of($input)->snake()->value();
         }
     }