Utils Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require c33s/utils
   

   No additional configuration is required—it’s a pure utility package with no service provider or facade.

2. First Use Case Import the utility you need (e.g., StringUtils for string manipulation):

   use C33s\Utils\StringUtils;
   
   $result = StringUtils::slugify('Hello World!');
   // Returns: 'hello-world'
   

3. Where to Look First

   • Browse the src directory for available utilities.
   • Check the README for quick examples (if provided).
   • Use IDE autocompletion to explore methods (e.g., StringUtils::, ArrayUtils::).

Implementation Patterns

Common Workflows

1. String Manipulation Use StringUtils for common tasks like:

   use C33s\Utils\StringUtils;
   
   // Slugify, truncate, or format strings
   StringUtils::truncate('Laravel is awesome', 10); // 'Laravel...'
   StringUtils::formatBytes(1024); // '1.00 KB'
   

2. Array Operations Leverage ArrayUtils for:

   use C33s\Utils\ArrayUtils;
   
   // Merge, diff, or flatten arrays
   ArrayUtils::mergeRecursive(['a' => 1], ['a' => 2]); // ['a' => 2]
   ArrayUtils::flatten([1, [2, 3]]); // [1, 2, 3]
   

3. Date/Time Handling Use DateTimeUtils for:

   use C33s\Utils\DateTimeUtils;
   
   // Parse, format, or compare dates
   DateTimeUtils::format('2023-01-01', 'Y-m-d H:i'); // '2023-01-01 00:00'
   

4. Validation Helpers Use ValidatorUtils for reusable validation logic:

   use C33s\Utils\ValidatorUtils;
   
   ValidatorUtils::isEmail('[email protected]'); // true
   

5. Integration with Laravel

   • Service Providers: Register utilities as singletons if needed:

     $this->app->singleton('slugify', function () {
         return new StringUtils();
     });
     

   • Helpers: Create facade-like helpers in app/Helpers/utils.php:

     if (!function_exists('slug')) {
         function slug($string) {
             return \C33s\Utils\StringUtils::slugify($string);
         }
     }
     

Gotchas and Tips

Pitfalls

1. No Facades or Service Providers

   • The package is stateless; all methods are static. Avoid expecting dependency injection or facades.
   • Workaround: Wrap utilities in a service class if you need DI.

2. Limited Documentation

   • Methods may lack PHPDoc or examples. Use IDE hints or inspect the source for usage.
   • Tip: Add PHPDoc comments to your local wrapper classes for clarity.

3. Edge Cases in String/Array Utils

   • slugify() may not handle Unicode well (e.g., é → e). Fix: Pre-process strings with mb_strtolower() or iconv().
   • ArrayUtils::diff() may not handle nested arrays as expected. Tip: Test with complex arrays before production use.

4. Performance Considerations

   • Some methods (e.g., ArrayUtils::flatten()) use recursion, which could hit stack limits for deep arrays. Tip: Use iterative approaches for large datasets.

Debugging Tips

• Enable Strict Typing: Add declare(strict_types=1); to catch type mismatches early.
• Log Input/Output: Debug complex array/string operations by logging inputs:

  \Log::debug('Input:', ['data' => $inputArray]);
  $result = ArrayUtils::flatten($inputArray);
  \Log::debug('Output:', ['result' => $result]);
  

Extension Points

1. Custom Utilities Extend existing classes (e.g., StringUtils) by creating a subclass:

   class CustomStringUtils extends StringUtils {
       public static function customSlugify($string) {
           return parent::slugify($string) . '-custom';
       }
   }
   

2. Add to Laravel’s app() Container Bind utilities to the container for easier testing:

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

3. Testing Mock utilities in tests using partial mocks:

   $mock = $this->partialMock(StringUtils::class, ['slugify']);
   $mock->method('slugify')->willReturn('mocked-slug');
   

4. Contributing Back

   • Fork the repo and add missing utilities (e.g., FileUtils, CollectionUtils).
   • Submit PRs with tests and PHPDoc.