Utils Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require sweetchuck/utils
   

   Register the service provider in config/app.php:

   'providers' => [
       Sweetchuck\Utils\UtilsServiceProvider::class,
   ],
   

2. First Use Case Access utility classes via the facade:

   use Sweetchuck\Utils\Facades\Utils;
   
   // Example: String manipulation
   $result = Utils::str()->slugify('Hello World!'); // Returns 'hello-world'
   
   // Example: Array helpers
   $flattened = Utils::arr()->flatten([1, [2, 3]]); // Returns [1, 2, 3]
   

3. Where to Look First

   • Facade: Sweetchuck\Utils\Facades\Utils (main entry point).
   • Documentation: Check the src/Sweetchuck/Utils directory for available classes (e.g., StringHelper, ArrayHelper).
   • Tests: The tests/ directory may contain usage examples (if any exist).

Implementation Patterns

Common Workflows

1. String Manipulation Use the str() helper for common string operations:

   // Slugify, truncate, or format strings
   Utils::str()->slugify('Test String');
   Utils::str()->truncate('Long text...', 10);
   

2. Array Operations Leverage arr() for array utilities:

   // Flatten, merge, or search arrays
   Utils::arr()->flatten([1, [2, 3]]);
   Utils::arr()->merge([1, 2], [2, 3]); // Returns [1, 2, 3]
   

3. Integration with Laravel

   • Service Container: Bind custom utilities to the container:

     $this->app->bind('custom.helper', function () {
         return new \Sweetchuck\Utils\CustomHelper();
     });
     

   • Service Providers: Extend the package’s UtilsServiceProvider for custom logic.

4. Blade Directives Register Blade helpers for frontend use:

   // In a service provider
   Blade::directive('slug', function ($expression) {
       return "<?php echo Utils::str()->slugify({$expression}); ?>";
   });
   

   Usage in Blade:

   <h1>{{ slug('My Title') }}</h1>>
   

5. Model Observers or Accessors Use utilities in Eloquent models:

   class Post extends Model
   {
       public function getSlugAttribute()
       {
           return Utils::str()->slugify($this->title);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Outdated Package

   • Last release in 2020 may lack PHP 8.x/9.x compatibility. Test thoroughly.
   • Check for breaking changes if upgrading PHP versions.

2. Limited Documentation

   • No formal docs; rely on:
     • Method names (e.g., slugify, flatten).
     • Tests (if available).
     • Source code (src/Sweetchuck/Utils/).

3. Facade Overhead

   • Facade usage (Utils::str()->method()) can be verbose. Consider:

     $stringHelper = app(Sweetchuck\Utils\StringHelper::class);
     $stringHelper->slugify('Test');
     

4. Namespace Conflicts

   • Ensure no naming collisions with existing classes (e.g., ArrayHelper vs. Laravel’s Arrayable).

5. No Type Safety

   • Methods may not enforce return types (e.g., slugify returns string, but no @return hints).

Debugging Tips

1. Check Method Existence If a method fails (e.g., Utils::str()->unknownMethod()), verify it exists in:

   \Sweetchuck\Utils\StringHelper::class
   

2. Inspect Source Code For undocumented behavior, review:

   vendor/sweetchuck/utils/src/Sweetchuck/Utils/StringHelper.php
   

3. Test Edge Cases

   • Empty strings/arrays:

     Utils::str()->slugify(''); // Returns ''
     Utils::arr()->flatten([]); // Returns []
     

Extension Points

1. Custom Helpers Extend existing classes:

   class ExtendedStringHelper extends \Sweetchuck\Utils\StringHelper
   {
       public function customMethod($str)
       {
           return strtoupper($str);
       }
   }
   

   Register in UtilsServiceProvider:

   $this->app->bind(
       \Sweetchuck\Utils\StringHelper::class,
       ExtendedStringHelper::class
   );
   

2. Add New Utilities Create a new helper class (e.g., DateHelper) and bind it:

   $this->app->singleton('utils.date', function () {
       return new \Sweetchuck\Utils\DateHelper();
   });
   

3. Override Facade Replace the facade to add custom methods:

   class CustomUtils extends \Sweetchuck\Utils\Facades\Utils
   {
       public static function customMethod()
       {
           return 'Custom logic';
       }
   }
   

   Update config/app.php to use CustomUtils.

Configuration Quirks

1. No Config File The package likely has no config/utils.php. All behavior is code-driven.

2. Service Provider Binding Ensure the provider is registered after Laravel’s core providers to avoid conflicts.

3. Facade Alias Verify the facade alias exists in config/app.php:

   'aliases' => [
       'Utils' => \Sweetchuck\Utils\Facades\Utils::class,
   ],