Support Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require roots/support
   

   No additional configuration is required—it’s a standalone helper library.

2. First Use Case Quickly sanitize user input or generate slugs:

   use Roots\Support\Str;
   
   $sanitized = Str::sanitize('user@input.com'); // "userinputcom"
   $slug = Str::slug('Hello World!'); // "hello-world"
   

3. Where to Look First

   • Core Classes: Focus on Roots\Support\Str, Roots\Support\Arr, Roots\Support\Path, and Roots\Support\Env.
   • Documentation: Check the GitHub repo for usage examples.
   • WordPress Integration: If used in a Roots WordPress project, check app/Helpers.php for common aliases.

Implementation Patterns

Common Workflows

1. String Manipulation Use Str for consistent string handling (e.g., truncation, sanitization, or formatting):

   $truncated = Str::limit('A very long string...', 20); // "A very long strin..."
   $titleCase = Str::title('hello world'); // "Hello World"
   

2. Array Utilities Leverage Arr for deep array operations (e.g., merging, plucking, or filtering):

   $merged = Arr::merge(['a' => 1], ['b' => 2]); // ['a' => 1, 'b' => 2]
   $values = Arr::pluck($users, 'name'); // Extract all 'name' values
   

3. Path Handling Use Path for filesystem operations (e.g., resolving paths or checking existence):

   $absolutePath = Path::make('app/Helpers.php')->absolute();
   if (Path::exists($absolutePath)) { ... }
   

4. Environment Handling Use Env for environment variable access, with fallback to Laravel's Env:

   $value = Env::get('APP_ENV'); // Falls back to Illuminate\Support\Env::get()
   

5. WordPress-Specific Helpers If integrated into a Roots WordPress project, use helpers like:

   use Roots\Support\WordPress;
   
   $postTitle = WordPress\getPostTitle($postId);
   $featuredImage = WordPress\getFeaturedImageUrl($postId);
   

Integration Tips

• Laravel Service Providers: Register helpers as Laravel bindings for global access:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      $this->app->singleton(Str::class, fn() => new Str());
      $this->app->singleton(Arr::class, fn() => new Arr());
      $this->app->singleton(Path::class, fn() => new Path());
      $this->app->singleton(Env::class, fn() => new Env());
  }
  

• Custom Extensions: Extend classes via traits or decorators:

  use Roots\Support\Str;
  
  class CustomStr extends Str {
      public static function customMethod($input) { ... }
  }
  

• Testing: Mock helpers in PHPUnit:

  $this->partialMock(Str::class, ['slug']);
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • roots/support may clash with Laravel’s built-in helpers (e.g., Str::of() vs. Roots\Support\Str::slug()).
   • Fix: Use fully qualified namespaces or aliases:

     use Roots\Support\Str as SupportStr;
     

   • Closure Namespace Fix: In v1.0.1, Roots\Closure was fixed to avoid conflicts with PHP's native Closure.

2. Environment Handling Quirks

   • Env::get() now attempts to use Illuminate\Support\Env::get() as a fallback. Ensure compatibility:

     if (class_exists('Illuminate\Support\Env')) {
         $value = Env::get('APP_ENV');
     }
     

3. WordPress-Specific Assumptions

   • Some methods (e.g., WordPress\getPostTitle()) assume a WordPress environment.
   • Fix: Wrap usage in checks:

     if (function_exists('get_post')) {
         $title = WordPress\getPostTitle($postId);
     }
     

4. Path Resolution Quirks

   • Path::make() uses Laravel’s storage_path() by default. For custom paths:

     $customPath = Path::make('custom/dir')->to('/absolute/path');
     

Debugging Tips

• Enable Debugging: Add a debug flag to helpers:

  Str::setDebug(true); // Logs operations to Laravel logs
  

• Check for Deprecations: Monitor the repo for breaking changes (e.g., renamed methods).

Extension Points

1. Add Custom Methods Override or extend classes via traits:

   use Roots\Support\Str;
   
   trait CustomStrMethods {
       public static function kebab($value) {
           return Str::slug($value, '-');
       }
   }
   
   class ExtendedStr extends Str {
       use CustomStrMethods;
   }
   

2. Configure Defaults Set global defaults in config/support.php (if the package supports it):

   'default_locale' => 'en_US',
   'sanitize_regex' => '/[^a-z0-9]/i',
   

3. Leverage Laravel Facades Create facades for cleaner syntax:

   // app/Facades/SupportStr.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   use Roots\Support\Str;
   
   class SupportStr extends Facade {
       protected static function getFacadeAccessor() { return Str::class; }
   }
   

   Usage:

   SupportStr::slug('Hello'); // "hello"