Support Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hyperf/support
   

   Ensure your composer.json includes "hyperf/support": "^3.1" or the latest stable version.

2. First Use Case: Leverage the Hyperf\Support\Traits and Hyperf\Support\Str utilities in your controllers, services, or models. Example:

   use Hyperf\Support\Str;
   
   $shortened = Str::limit('This is a very long string', 10); // "This is a..."
   

3. Key Entry Points:

   • Traits: Hyperf\Support\Traits\Arrayable, Hyperf\Support\Traits\Jsonable, Hyperf\Support\Traits\Macroable.
   • Str Helper: String manipulation utilities (e.g., Str::snake(), Str::camel()).
   • Collection Extensions: Enhanced collection methods (e.g., Collection::when()).

   Check the Hyperf Framework documentation for trait/utility integration with Hyperf’s core.

Implementation Patterns

Common Workflows

1. String Manipulation: Use Str for consistent string transformations across the app.

   Str::of('user_name')->title(); // "User Name"
   Str::of('user_name')->lower(); // "user_name"
   

2. Array/Collection Utilities: Extend collections with custom logic using Macroable trait.

   use Hyperf\Support\Traits\Macroable;
   
   class CustomCollection extends Collection
   {
       use Macroable;
   }
   
   // Register a macro in a service provider:
   $collection->macro('customMethod', function () {
       return $this->filter(fn ($item) => $item > 10);
   });
   

3. JSON/Array Conversion: Use Arrayable and Jsonable traits for seamless serialization.

   class User implements Arrayable, Jsonable
   {
       use \Hyperf\Support\Traits\Arrayable;
       use \Hyperf\Support\Traits\Jsonable;
   
       public function toArray(): array
       {
           return ['name' => $this->name, 'email' => $this->email];
       }
   }
   

4. Conditional Logic: Chain when()/unless() for dynamic collection operations.

   $collection->when($condition, fn ($coll) => $coll->filter(...));
   

Integration Tips

• Service Providers: Register custom macros or helpers in Hyperf\Contract\ProviderInterface.
• Middleware: Use Str utilities to validate/sanitize request data.
• Testing: Mock Str or collection methods in PHPUnit tests for isolated logic.

Gotchas and Tips

Pitfalls

1. Trait Conflicts: Avoid naming collisions when using multiple Macroable traits. Prefix macros (e.g., macro('app_customMethod', ...)).

2. Str Immutability: Str::of() returns a new Stringable instance. Chain methods for clarity:

   // Bad: Mutates original string (if not handled properly)
   $str = Str::of('test');
   $str->upper();
   
   // Good: Immutable chain
   $result = Str::of('test')->upper()->value();
   

3. Collection Macros in Hyperf: Ensure macros are registered after the Collection class is bootstrapped (e.g., in a provider’s onRegister).

4. Performance: Heavy string operations (e.g., regex in Str::replace()) may impact performance. Cache results if reused.

Debugging

• Macro Debugging: Use Collection::getMacro('macroName') to inspect registered macros.

  $macro = collect([])->getMacro('customMethod');
  dump($macro);
  

• Str Method Chaining: If a method fails silently, check for typos or missing value() at the end of the chain.

Extension Points

1. Custom Str Macros: Extend Str with domain-specific methods in a provider:

   Str::macro('slugify', function ($string) {
       return Str::of($string)->slug();
   });
   

2. Arrayable/Jsonable Overrides: Override toArray()/toJson() for nested structures:

   public function toArray(): array
   {
       return [
           'data' => $this->relations->toArray(),
           'meta' => ['count' => $this->count],
       ];
   }
   

3. Hyperf-Specific: Combine with Hyperf’s Context for request-scoped utilities:

   use Hyperf\Context\Context;
   
   $requestId = Context::get('request_id');
   $str = Str::of($requestId)->padLeft(8, '0');
   

4. Testing Utilities: Use Hyperf\Support\Testing\TestCase for assertions:

   $this->assertStringContainsString('test', Str::of('hello test')->value());