Utilities Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require windwalker/utilities ^4.0
   

   Ensure your composer.json includes the package under require.

2. First Use Case Import and use the StringHelper for common string manipulations:

   use Windwalker\Utilities\Helper\StringHelper;
   
   $result = StringHelper::slugify('Hello World!'); // Returns 'hello-world'
   

3. Where to Look First

   • Documentation: Windwalker Utilities Docs
   • Source Code: Browse the Helper directory for utility classes.
   • Examples: Check the tests folder for practical usage patterns.

Implementation Patterns

Common Workflows

1. String Manipulation

• Slugify: Convert strings to URL-friendly slugs.

  $slug = StringHelper::slugify('Laravel 10 Guide');
  

• Truncate: Shorten strings with ellipsis.

  $shortened = StringHelper::truncate('A very long string...', 10);
  

2. Array Utilities

• Merge Arrays Recursively:

  $merged = ArrayHelper::mergeRecursive(
      ['a' => 1, 'b' => 2],
      ['a' => 2, 'c' => 3]
  ); // Returns ['a' => [1, 2], 'b' => 2, 'c' => 3]
  

• Pluck Values:

  $values = ArrayHelper::pluck($collection, 'key');
  

3. File and Path Handling

• Normalize Paths:

  $normalized = PathHelper::normalize('/path/with/../duplicates');
  

• Check File Extensions:

  $isImage = FileHelper::isImage('image.jpg');
  

4. Date/Time Utilities

• Format Dates:

  $formatted = DateHelper::format('2023-10-01', 'Y-m-d H:i:s');
  

• Time Ago:

  $timeAgo = DateHelper::timeAgo('2023-10-01 12:00:00');
  

5. Integration with Laravel

• Service Provider Binding (if needed):

  // config/app.php
  'aliases' => [
      'StringHelper' => Windwalker\Utilities\Helper\StringHelper::class,
  ],
  

• Facade Usage (if extended):

  use Windwalker\Utilities\Facades\StringHelperFacade;
  
  $slug = StringHelperFacade::slugify('Test String');
  

Best Practices

• Prefer Static Methods: The package is designed for lightweight, stateless utilities.
• Compose Helpers: Chain methods for complex operations (e.g., slugify + truncate).
• Leverage Laravel’s Service Container: Bind helpers as singletons if reused frequently:

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

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • The package uses Windwalker\Utilities namespace. Ensure no conflicts with other Windwalker packages or custom namespaces.
   • Fix: Use fully qualified class names or aliases in Laravel’s config/app.php.

2. Performance Overhead

   • Some methods (e.g., ArrayHelper::mergeRecursive) may be slower for large datasets.
   • Tip: Cache results if used repeatedly in loops.

3. Undocumented Methods

   • The package is lightweight, but not all methods are documented in the README.
   • Tip: Check the source code or tests for undocumented features.

4. Laravel-Specific Assumptions

   • Some helpers (e.g., FileHelper) assume filesystem operations are Laravel-compatible.
   • Tip: Test file operations in your environment, especially on shared hosting.

Debugging Tips

1. Enable Strict Typing If using PHP 7.4+, enable declare(strict_types=1) at the top of your file to catch type-related issues early.

2. Log Helper Outputs For complex operations (e.g., ArrayHelper::mergeRecursive), log intermediate results:

   \Log::debug('Merged array:', $mergedArray);
   

3. Check for Deprecations The package follows semantic versioning (^4.0). Monitor the changelog for breaking changes.

Extension Points

1. Custom Helpers Extend existing helpers by creating child classes:

   use Windwalker\Utilities\Helper\StringHelper;
   
   class CustomStringHelper extends StringHelper {
       public static function customSlugify($string) {
           return parent::slugify($string) . '-custom';
       }
   }
   

2. Add New Utilities Contribute by adding methods to existing helpers or creating new ones. Follow the contribution guidelines.

3. Facade Integration Create a facade for easier access (if not already provided):

   // app/Facades/CustomHelperFacade.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class CustomHelperFacade extends Facade {
       protected static function getFacadeAccessor() {
           return 'custom.helper';
       }
   }
   

   Register in a service provider:

   $this->app->bind('custom.helper', function () {
       return new \Windwalker\Utilities\Helper\StringHelper();
   });
   

Configuration Quirks

• No Config File: The package is zero-config. All functionality is stateless and accessed via static methods.
• Environment-Specific Paths: For PathHelper, ensure paths are resolved relative to Laravel’s base_path() if needed:

  $absolutePath = base_path($relativePath);