Utils Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in a Laravel/Symfony project:

   composer require bastsys/utils-bundle
   

   For Laravel, manually register the bundle in config/app.php under providers (Symfony-style bundles may not work directly; check for Laravel adapters or use standalone utilities).

2. First Use Case The package provides utility classes like StringUtils, ArrayUtils, and FileUtils. Start with a simple string manipulation:

   use Bastsys\UtilsBundle\Utils\StringUtils;
   
   $text = StringUtils::slugify('Hello World!');
   // Output: "hello-world"
   

3. Where to Look First

   • Documentation: Check the GitHub README for basic usage.
   • Utils Classes: Browse src/Utils/ for available utilities (e.g., StringUtils, ArrayUtils).
   • Tests: If available, review tests/ for real-world examples (though the package has no stars/dependents, tests may be minimal).

Implementation Patterns

Common Workflows

1. String Manipulation Use StringUtils for common tasks like slugifying, truncating, or formatting:

   $slug = StringUtils::slugify('Laravel 10 Guide');
   $truncated = StringUtils::truncate('Long text...', 10);
   

2. Array Operations Leverage ArrayUtils for nested array operations:

   $flattened = ArrayUtils::flatten(['a' => ['b', 'c']]); // ['b', 'c']
   $merged = ArrayUtils::mergeRecursive(['a' => 1], ['a' => 2]); // ['a' => 2]
   

3. File Handling Use FileUtils for path/filename operations (e.g., generating unique filenames):

   $uniqueName = FileUtils::generateUniqueFilename('image', 'jpg');
   // Output: "image_1678901234.jpg"
   

4. Integration with Laravel

   • Service Providers: Bind utilities to the container for global access:

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

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

     if (!function_exists('slugify')) {
         function slugify($text) {
             return StringUtils::slugify($text);
         }
     }
     

5. Validation Combine with Laravel’s validator for custom rules:

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($data, [
       'title' => ['required', function ($attribute, $value, $fail) {
           if (StringUtils::length($value) > 100) {
               $fail('Title must be less than 100 characters.');
           }
       }]
   ]);
   

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel Compatibility

   • The package is Symfony-focused. Some utilities (e.g., dependency injection) may not work out-of-the-box in Laravel.
   • Fix: Use standalone classes or wrap them in Laravel services.

2. No Active Maintenance

   • Last release: 2021-01-31. Test thoroughly for edge cases (e.g., Unicode handling in StringUtils).
   • Tip: Fork and extend if critical functionality is missing.

3. Limited Documentation

   • Assume minimal docs. Rely on:
     • Method names (e.g., StringUtils::camelCase()).
     • Tests (if any).
     • Source code (src/Utils/).

4. Performance Overhead

   • Some utilities (e.g., recursive array operations) may be slow for large datasets.
   • Tip: Cache results or use Laravel’s built-ins (e.g., collect()) where possible.

Debugging Tips

1. Check Input/Output For StringUtils or ArrayUtils, log inputs/outputs to debug:

   \Log::debug('Slugify input:', ['text' => 'Café']);
   $slug = StringUtils::slugify('Café');
   \Log::debug('Slugify output:', ['slug' => $slug]);
   

2. Unicode Handling Some string methods may mishandle non-ASCII characters (e.g., é, ñ).

   • Fix: Pre-process strings with mb_strtolower() or use Str::of() in Laravel.

3. FileUtils Quirks

   • Path separators may not be OS-agnostic. Use Laravel’s Storage facade or Str::of() for consistency:

     use Illuminate\Support\Str;
     $path = Str::of(FileUtils::generateUniqueFilename('file', 'txt'))->replace('/', DIRECTORY_SEPARATOR);
     

Extension Points

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

   namespace App\Utils;
   
   use Bastsys\UtilsBundle\Utils\StringUtils;
   
   class AppStringUtils extends StringUtils {
       public static function customMethod($text) {
           return parent::slugify($text) . '_app';
       }
   }
   

2. Add to Laravel’s Str Helper Override or extend Laravel’s Str helper to include package methods:

   // app/Providers/AppServiceProvider.php
   use Illuminate\Support\Str;
   use Bastsys\UtilsBundle\Utils\StringUtils;
   
   Str::macro('bastSlugify', function ($text) {
       return StringUtils::slugify($text);
   });
   

   Usage:

   $slug = Str::bastSlugify('Hello World');
   

3. Testing Mock utilities in tests to isolate logic:

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