Alpha Helper Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sinarajabpour1998/alpha-helper
   

   Publish the config (if applicable):

   php artisan vendor:publish --provider="AlphaHelper\AlphaHelperServiceProvider"
   

2. First Use Case

   • Helper Functions: Use AlphaHelper::slugify('Hello World') directly in controllers/views.
   • Validators: Extend Laravel’s validation with AlphaHelper::validateAlphaNumeric($request->input('field')).

3. Where to Look First

   • Documentation: Check vendor/sinarajabpour1998/alpha-helper/README.md for function lists.
   • Facade: AlphaHelper facade provides all helper methods (e.g., AlphaHelper::randomString()).
   • Service Provider: Inspect AlphaHelperServiceProvider for bootstrapped helpers.

Implementation Patterns

Common Workflows

1. String Manipulation

   // Slugify in a controller
   $slug = AlphaHelper::slugify($request->title);
   
   // Random string generation
   $token = AlphaHelper::randomString(16);
   

2. Validation Integration

   // Custom rule in FormRequest
   $this->validate($request, [
       'username' => ['required', 'string', AlphaHelper::class . '@validateAlphaNumeric']
   ]);
   

3. Array/Collection Helpers

   // Flatten nested arrays
   $flatArray = AlphaHelper::flattenArray($nestedArray);
   
   // Merge arrays with custom logic
   $merged = AlphaHelper::mergeArrays($array1, $array2, ['key' => 'custom_merge']);
   

4. Date/Time Utilities

   // Format dates consistently
   $formatted = AlphaHelper::formatDate($date, 'Y-m-d H:i:s');
   
   // Timezone conversions
   $utcTime = AlphaHelper::convertTimezone($date, 'UTC');
   

5. API Response Wrapping

   // Standardized API responses
   return AlphaHelper::apiResponse($data, 'Success', 200);
   

Integration Tips

• Service Container Binding: Bind custom helpers to the container for dependency injection:

  $this->app->bind('custom.helper', function () {
      return new AlphaHelper();
  });
  

• Blade Directives: Register helpers as Blade directives for frontend use:

  Blade::directive('slugify', function ($expression) {
      return "<?php echo AlphaHelper::slugify({$expression}); ?>";
  });
  

• Event Listeners: Use helpers in event listeners for reusable logic:

  public function handle()
  {
      $cleanData = AlphaHelper::sanitizeInput($this->data);
      // Process $cleanData
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • If using AlphaHelper facade, ensure no other package/class shadows the namespace.
   • Fix: Use fully qualified names (e.g., \AlphaHelper\AlphaHelper::slugify()).

2. Validation Rule Conflicts

   • Custom validation rules (e.g., validateAlphaNumeric) may conflict with Laravel’s built-in rules.
   • Fix: Prefix rules with a unique identifier (e.g., alpha|alpha_numeric).

3. Performance Overhead

   • Heavy helpers (e.g., recursive array flattening) may slow down high-traffic routes.
   • Fix: Cache results or use lazy evaluation where possible.

4. Undocumented Methods

   • Some helper methods may lack documentation or edge-case handling.
   • Fix: Inspect the source (vendor/sinarajabpour1998/alpha-helper/src/) for undocumented features.

Debugging Tips

• Log Helper Outputs:

  \Log::debug('Slugified:', ['input' => $input, 'output' => AlphaHelper::slugify($input)]);
  

• Test Edge Cases:
  • Empty strings, null, or malformed inputs (e.g., AlphaHelper::slugify(null)).
• Disable Helpers Temporarily:

  // Override in tests
  AlphaHelper::shouldReceive('slugify')->andReturn('test-slug');
  

Extension Points

1. Custom Helpers

   • Extend the package by creating a subclass:

     namespace App\Helpers;
     
     use AlphaHelper\AlphaHelper as BaseHelper;
     
     class AppHelper extends BaseHelper {
         public static function customHelper($input) {
             return parent::slugify($input) . '-app';
         }
     }
     

2. Configuration Overrides

   • Publish the config and override defaults (e.g., slugify separators):

     'slugify' => [
         'separator' => '-',
         'lowercase' => true,
     ],
     

3. Macro Support

   • Add macros to the AlphaHelper facade for reusable logic:

     AlphaHelper::macro('customMacro', function ($arg) {
         return "Processed: {$arg}";
     });
     

4. Testing

   • Mock the facade in PHPUnit:

     $this->partialMock(AlphaHelper::class, ['slugify'])
          ->shouldReceive('slugify')
          ->andReturn('mocked-slug');