Extended Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require open-southeners/extended-php
   

   • No configuration required; autoloads via Composer.

2. First Use Case

   • String Manipulation: Use Str::camel_case('hello_world') for instant conversion.
   • Array Utilities: Leverage Arr::dot('array', 'key') for nested array access.
   • Collection Helpers: Extend Laravel Collections with collect($array)->toJsonApi() for API responses.

3. Where to Look First

   • Documentation: Check the src/Extended namespace for core utilities.
   • Facade: Use Extended::helper() for dynamic method calls (e.g., Extended::helper('str', 'snake_case')).
   • Examples: Browse tests/ for real-world usage patterns.

Implementation Patterns

Core Workflows

1. String Utilities

   • Pattern: Replace Str::of($str)->slug() with Extended::str()->slug($str) for chaining.
   • Example:

     $title = Extended::str()
         ->title_case('hello_world')
         ->limit(50)
         ->toString();
     

2. Array/Collection Extensions

   • Pattern: Use Arr::wrap($value) or collect($data)->groupBy('category') for Laravel integration.
   • Example:

     $grouped = collect($users)->groupBy('role', Extended::arr());
     

3. DateTime Helpers

   • Pattern: Format dates with Extended::date()->format('Y-m-d', $timestamp).
   • Example:

     $formatted = Extended::date()->diffForHumans($createdAt);
     

4. API Response Shortcuts

   • Pattern: Return JSON:API responses with Extended::response()->jsonApi($data, $meta).
   • Example:

     return Extended::response()->jsonApi($posts, ['page' => 1]);
     

Integration Tips

• Laravel Blade: Use @php use Extended\Str; @endphp to access helpers directly in views.
• Service Providers: Register facade aliases in config/app.php for global access:

  'aliases' => [
      'Extended' => Extended\Facades\Extended::class,
  ],
  

• Testing: Mock Extended facade in tests:

  $this->partialMock(Extended::class, ['helper']);
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Issue: Extended\Str may conflict with Laravel’s Illuminate\Support\Str.
   • Fix: Prefix calls (e.g., Extended::str()->slug()) or alias the facade.

2. Performance Overhead

   • Issue: Heavy chaining (e.g., Extended::str()->...->...) may impact performance.
   • Fix: Cache results or use direct methods (e.g., Extended::str()->slug($str)).

3. Undocumented Methods

   • Issue: Some utilities (e.g., Extended::misc()->randomize()) lack docs.
   • Fix: Check tests/ or use php artisan tinker to explore:

     Extended::helper('misc', 'randomize', [1, 10]);
     

Debugging Tips

• Enable Debug Mode:

  Extended::setDebug(true); // Logs helper calls to Laravel logs.
  

• Inspect Available Helpers:

  dd(Extended::availableHelpers()); // Lists all registered utilities.
  

Extension Points

1. Custom Helpers

   • Register new helpers via service provider:

     Extended::addHelper('custom', function ($input) {
         return strtoupper($input);
     });
     

   • Usage: Extended::helper('custom', 'hello').

2. Override Defaults

   • Extend core classes (e.g., Extended\Str) by publishing config:

     php artisan vendor:publish --provider="OpenSoutheners\Extended\ExtendedServiceProvider"
     

   • Modify config/extended.php to override defaults (e.g., slug_separator).

3. Facade Customization

   • Bind the facade to a custom class in AppServiceProvider:

     Extended::swap(new CustomExtendedHelper());