Helpers Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atournayre/helpers
   

   Add the service provider to config/app.php under providers:

   ATournayre\Helpers\HelpersServiceProvider::class,
   

2. First Use Case Quickly generate a UUID:

   use ATournayre\Helpers\Facades\Helpers;
   
   $uuid = Helpers::uuid(); // e.g., "550e8400-e29b-41d4-a716-446655440000"
   

3. Where to Look First

   • Facade: Helpers (aliases \ATournayre\Helpers\Facades\Helpers)
   • Documentation: Check the package’s README.md or generated PHPDoc blocks (if available).
   • Source: Browse src/HelpersServiceProvider.php for registered helpers.

Implementation Patterns

Common Workflows

1. Data Transformation Use Helpers::snake_case() or Helpers::camel_case() for string conversions:

   $snake = Helpers::snake_case('userName'); // "user_name"
   $camel = Helpers::camel_case('user_name'); // "userName"
   

2. Validation & Sanitization Clean user input with Helpers::sanitize():

   $cleanInput = Helpers::sanitize("<script>alert('xss')</script>");
   

3. Date/Time Utilities Parse or format dates:

   $formatted = Helpers::formatDate('2023-04-26', 'Y-m-d H:i:s'); // "2023-04-26 00:00:00"
   

4. Array Manipulation Merge or diff arrays:

   $merged = Helpers::arrayMergeRecursive(['a' => 1], ['a' => 2]); // ['a' => 2]
   

5. File & Path Handling Generate paths or check extensions:

   $path = Helpers::path('storage/app/uploads'); // Full path resolution
   $isImage = Helpers::isImage('file.jpg'); // true
   

6. Integration with Laravel Use helpers in Service Providers, Middleware, or Controllers:

   // Example: Middleware for UUID generation
   public function handle($request, Closure $next) {
       $request->merge(['uuid' => Helpers::uuid()]);
       return $next($request);
   }
   

7. Blade Directives (if supported) Register custom Blade helpers in AppServiceProvider:

   Blade::directive('uuid', function () {
       return "<?php echo \\ATournayre\\Helpers\Facades\\Helpers::uuid(); ?>";
   });
   

   Usage in Blade:

   <div>{{ uuid() }}</div>
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The package uses ATournayre\Helpers; ensure no naming conflicts with your app’s classes.
   • Fix: Use fully qualified namespaces or aliases.

2. Undefined Methods

   • The package may lack PHPDoc or IDE autocompletion. Check HelpersServiceProvider for registered methods.
   • Fix: Use Helpers::method() and catch BadMethodCallException:

     try {
         Helpers::unknownMethod();
     } catch (\BadMethodCallException $e) {
         Log::error("Helper method not found: " . $e->getMessage());
     }
     

3. Date Handling Quirks

   • formatDate() defaults to Y-m-d. Override with custom formats:

     $custom = Helpers::formatDate('now', 'd/m/Y'); // "26/04/2023"
     

4. Array Merge Behavior

   • arrayMergeRecursive() may not handle sparse arrays as expected. Test edge cases:

     $result = Helpers::arrayMergeRecursive([1 => 'a'], [2 => 'b']); // [1 => 'a', 2 => 'b']
     

5. File Operations

   • Methods like isImage() or path() rely on filesystem permissions. Test in a staging environment first.

Debugging Tips

1. Log Helper Outputs Wrap helper calls in Log::debug() to inspect results:

   Log::debug('UUID:', ['value' => Helpers::uuid()]);
   

2. Check Service Provider Registration Verify the provider is loaded in config/app.php and no errors appear on boot:

   php artisan package:discover
   

3. Fallback Logic Implement fallback logic for critical helpers:

   $uuid = method_exists(Helpers::class, 'uuid')
       ? Helpers::uuid()
       : Str::uuid()->toString();
   

Extension Points

1. Add Custom Helpers Extend the Helpers facade by binding new methods in AppServiceProvider:

   Helpers::extend('customHelper', function () {
       return 'Custom Value';
   });
   

   Usage:

   Helpers::customHelper(); // "Custom Value"
   

2. Override Existing Methods Use Laravel’s macro feature to replace helper behavior:

   \ATournayre\Helpers\Facades\Helpers::macro('uuid', function () {
       return Str::orderedUuid();
   });
   

3. Publish Config (if applicable) If the package includes config (unlikely given its simplicity), publish it:

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