Darvin Utils Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require darvinstudio/darvin-utils
   

   No publisher or service provider is required—utilities are statically accessible via the DarvinUtils facade.

2. First Use Case Quickly validate an email format or generate a slug:

   use DarvinUtils\Facades\DarvinUtils;
   
   // Validate email
   $isValid = DarvinUtils::validateEmail('test@example.com');
   
   // Generate slug
   $slug = DarvinUtils::slugify('Hello World!');
   

3. Where to Look First

   • Facade: DarvinUtils\Facades\DarvinUtils (primary entry point).
   • Documentation: Check the GitHub repo (if available) or inspect the src/DarvinUtils namespace for methods.
   • Test Suite: Run php artisan test (if tests exist) to see real-world usage examples.

Implementation Patterns

Common Workflows

1. Data Sanitization

   $cleanedInput = DarvinUtils::sanitizeInput($userInput, 'text');
   

   • Use for form inputs, API payloads, or user-generated content.

2. String Manipulation

   $truncated = DarvinUtils::truncate('Long string here', 10);
   $reversed = DarvinUtils::reverse('hello');
   

   • Ideal for preview text, dynamic UI elements, or data transformations.

3. Array Utilities

   $flattened = DarvinUtils::flattenArray(['a' => ['b' => 1]]);
   $diff = DarvinUtils::arrayDiff(['a', 'b'], ['b', 'c']);
   

   • Useful for API responses, nested data processing, or comparisons.

4. Date/Time Helpers

   $formatted = DarvinUtils::formatDate('2023-01-01', 'Y-m-d H:i');
   $isFuture = DarvinUtils::isFutureDate('2025-01-01');
   

   • Replace Carbon for lightweight date checks or formatting.

5. Integration with Laravel

   • Form Requests:

     public function rules()
     {
         return [
             'email' => ['required', 'string', function ($attribute, $value, $fail) {
                 if (!DarvinUtils::validateEmail($value)) {
                     $fail('Invalid email format.');
                 }
             }]
         ];
     }
     

   • Middleware:

     public function handle($request, Closure $next)
     {
         $request->merge(['slug' => DarvinUtils::slugify($request->title)]);
         return $next($request);
     }
     

Gotchas and Tips

Pitfalls

1. No Dependency Injection

   • Utilities are static. Avoid overusing them in complex logic where dependency injection (e.g., Laravel services) would be better.
   • Example: Don’t use DarvinUtils::validateEmail() in a service container-bound class if you later need to mock it.

2. Limited Error Handling

   • Methods like validateEmail() return booleans or sanitized values without exceptions. Handle edge cases explicitly:

     if (!DarvinUtils::validateEmail($email)) {
         throw new \InvalidArgumentException('Invalid email');
     }
     

3. Undocumented Methods

   • The package lacks stars and recent updates. Assume methods may change or lack thorough testing. Prefer well-documented alternatives (e.g., Laravel’s built-in Str::slug() over slugify()).

4. Performance Overhead

   • Some utilities (e.g., flattenArray()) may be inefficient for large datasets. Benchmark before use in performance-critical paths.

Debugging Tips

• Check Method Existence:

  if (method_exists(DarvinUtils::class, 'methodName')) {
      // Safe to call
  }
  

• Inspect Source: Dive into vendor/darvinstudio/darvin-utils/src/DarvinUtils.php to verify behavior or extend functionality.

Extension Points

1. Custom Utilities Extend the facade by binding additional methods in a service provider:

   DarvinUtils::extend(function ($utils) {
       $utils->customMethod = function ($input) {
           return strtoupper($input);
       };
   });
   

2. Override Defaults Replace core methods by publishing and modifying the package’s config (if available) or by creating a decorator pattern.

3. Testing Since the package lacks tests, write your own:

   public function testSlugify()
   {
       $this->assertEquals('hello-world', DarvinUtils::slugify('Hello World!'));
   }
   

Config Quirks

• No Config File: All utilities are hardcoded. Adjust logic via method parameters or wrapper classes if needed.