Support Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require arcanedev/support
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="ArcaneDev\Support\ArcaneDevSupportServiceProvider" --tag="config"
   

2. Key Entry Points

   • ArcaneDev\Support\Facades\Support: The main facade for utility methods.
   • config/arcane-dev-support.php: Centralized configuration for package settings.
   • app/Providers/ArcaneDevSupportServiceProvider.php: Registers macros, helpers, and bindings.

3. First Use Case Use the Support::str() helper to sanitize and manipulate strings:

   use ArcaneDev\Support\Facades\Support;
   
   $cleaned = Support::str()->slug('Hello World!'); // Returns "hello-world"
   

Implementation Patterns

Common Workflows

1. String Manipulation Chain methods for robust string handling:

   Support::str()
       ->trim('  extra spaces  ')
       ->slug('User Input')
       ->toUpper();
   

2. Collection Enhancements Extend Laravel collections with custom methods:

   $collection = collect([1, 2, 3]);
   $chunked = $collection->chunkBy(2); // [[1, 2], [3]]
   

3. Model/Query Helpers Add scopes or accessors dynamically:

   // In a model:
   use ArcaneDev\Support\Traits\HasScopes;
   
   class Post extends Model
   {
       use HasScopes;
   
       public function scopePublished($query)
       {
           return $query->where('published_at', '<=', now());
       }
   }
   

4. Request/Response Utilities Validate and transform requests/responses:

   $validated = Support::request()->validate([
       'email' => 'required|email',
   ]);
   

5. Macros & Customization Register global helpers in AppServiceProvider:

   Support::macro('customHelper', function ($input) {
       return strtolower($input) . '_suffix';
   });
   

Integration Tips

• Leverage Traits: Use HasScopes, HasAccessors, or HasMutators in models for reusable logic.
• Configuration: Override defaults in config/arcane-dev-support.php (e.g., default_locale, timezone).
• Testing: Mock the Support facade in tests:

  $this->mock(Support::class)->shouldReceive('str()->slug')->andReturn('test-slug');
  

Gotchas and Tips

Pitfalls

1. Facade vs. Helper Confusion

   • Use Support::str() for chaining, but direct helpers like Support::slug() may not chain.
   • Fix: Stick to the facade for consistency.

2. Collection Method Conflicts

   • Custom collection methods might clash with Laravel’s built-ins.
   • Fix: Prefix methods (e.g., chunkBy() → arcaneChunkBy()) or namespace them.

3. Overriding Default Config

   • Forgetting to publish the config can lead to unexpected behavior.
   • Fix: Always publish and check config/arcane-dev-support.php.

4. Macro Scope Leaks

   • Global macros registered in AppServiceProvider can affect all tests.
   • Fix: Use Support::macro() sparingly or reset macros in setUp():

     public function setUp(): void
     {
         Support::macro('customHelper', null); // Unregister
         parent::setUp();
     }
     

Debugging Tips

• Check Registered Macros:

  dd(Support::getMacroMethods()); // List all registered macros
  

• Inspect Collection Methods:

  dd(collect([])->getMethods()); // Debug available methods
  

• Enable Debug Mode: Set debug to true in config to log helper usage (helpful for troubleshooting).

Extension Points

1. Add Custom Helpers Extend the Support facade in a service provider:

   Support::extend('custom', function () {
       return new class {
           public function example($input) { return $input * 2; }
       };
   });
   

   Usage:

   Support::custom()->example(5); // Returns 10
   

2. Create Reusable Traits Build domain-specific traits (e.g., HasSoftDeletesWithAudit) and share them across projects.

3. Override Default Behaviors Replace core helpers by redefining them in your AppServiceProvider:

   Support::macro('slug', function ($string) {
       return strtolower(preg_replace('/[^a-z0-9]+/', '-', $string));
   });
   

4. Localization Support Use the trans helper with custom fallback logic:

   Support::trans('messages.welcome', [], 'en', 'Default Welcome');