Cutlet Helper Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dizatech/dizatech-helper
   

   Ensure dizatech/dizatech-helper is added to providers in config/app.php:

   Dizatech\Helper\HelperServiceProvider::class,
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="Dizatech\Helper\HelperServiceProvider" --tag="config"
   

   Locate config at config/helper.php.

3. First Use Case: Iranian Phone Validation

   use Dizatech\Helper\Facades\Helper;
   
   $isValid = Helper::validateIranianPhone('09123456789'); // Returns bool
   

Implementation Patterns

Common Workflows

1. Validation Helpers

   // Iranian-specific validations
   Helper::validateIranianNationalCode('1234567890'); // National code
   Helper::validateIranianPhone('09121234567');     // Mobile/landline
   Helper::validateIranianPostalCode('1234567890');  // Postal code
   
   // Generic helpers
   Helper::isPersian($string); // Check if string contains Persian chars
   Helper::persianToEnglishNumber($string); // Convert Persian numbers to English
   

2. Date/Time Helpers (Jalali Calendar)

   // Convert Gregorian to Jalali (Persian) date
   $jalaliDate = Helper::gregorianToJalali('2023-12-31');
   // Format Jalali date
   Helper::formatJalaliDate($jalaliDate, 'Y/m/d'); // e.g., '1402/10/10'
   

3. String Manipulation

   // Remove diacritics (e.g., 'café' → 'cafe')
   Helper::removeDiacritics($string);
   
   // Persian number to English (e.g., '۱۲۳' → '123')
   Helper::persianToEnglishNumber('۱۲۳۴۵۶۷۸۹۰');
   

4. Integration with Laravel Validation

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($request->all(), [
       'national_code' => 'required|iranian_national_code',
       'phone'         => 'required|iranian_phone',
   ]);
   

Best Practices

• Facade Usage: Prefer Helper::method() over direct class instantiation for cleaner code.
• Config Overrides: Customize validation rules in config/helper.php (e.g., phone length).
• Jalali Date Handling: Use Helper::jalali() for consistent date formatting in Persian apps.
• Localization: Combine with Laravel’s localization for Persian-specific UI/UX.

Gotchas and Tips

Pitfalls

1. Deprecated Package Name

   • The package was originally named cutlet-helper but is now dizatech-helper. Ensure your composer.json and autoload reflect the correct namespace:

     "autoload": {
         "psr-4": {
             "Dizatech\\Helper\\": "vendor/dizatech/helper/src"
         }
     }
     

2. Jalali Date Edge Cases

   • The Jalali calendar’s leap years can cause off-by-one errors. Test boundary dates (e.g., 1402/10/10 → 2023-12-31).
   • Fix: Use Helper::jalali()->format() for consistent output.

3. Validation Rule Conflicts

   • Custom validation rules (e.g., iranian_phone) may conflict with Laravel’s built-in rules. Explicitly namespace them:

     'phone' => 'required|iranian_phone', // Works if published config is loaded
     

4. Persian Number Handling

   • persianToEnglishNumber() may fail on mixed strings (e.g., '۱۲۳abc'). Sanitize input first:

     preg_match('/[\u06F0-\u06F9]/u', $string) ? Helper::persianToEnglishNumber($string) : $string;
     

Debugging Tips

• Enable Debug Mode: Set debug to true in config/helper.php to log validation errors.
• Check Published Config: Verify config/helper.php exists and is loaded. Run:

  php artisan config:clear
  

  if changes aren’t reflected.

Extension Points

1. Custom Validation Rules Extend the validator by adding rules to config/helper.php:

   'validation' => [
       'custom_rules' => [
           'iranian_ssn' => 'Dizatech\Helper\Rules\IranianSSN',
       ],
   ],
   

2. Jalali Date Extensions Override default Jalali logic by publishing the config and modifying:

   'jalali' => [
       'leap_year_threshold' => 30, // Customize leap year calculation
   ],
   

3. Helper Facade Extensions Add custom methods to the facade by extending the HelperServiceProvider:

   public function boot()
   {
       Helper::extend('customMethod', function ($param) {
           return "Custom: {$param}";
       });
   }
   

Performance Notes

• Caching: Jalali date conversions are lightweight but cache results if used frequently in loops:

  $cachedJalali = Cache::remember("jalali_{$gregorianDate}", 3600, function () use ($gregorianDate) {
      return Helper::gregorianToJalali($gregorianDate);
  });