Toolset Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require achinon/toolset
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Achinon\Toolset\ToolsetServiceProvider::class,
   ],
   

2. First Use Case: Helper Functions The package provides a Toolset facade for common utilities. Access it immediately:

   use Achinon\Toolset\Facades\Toolset;
   
   // Example: Generate a UUID
   $uuid = Toolset::uuid();
   

3. Where to Look First

   • Facade API: Check app/Toolset.php (auto-generated) for available methods.
   • Documentation: If available, review the README.md for core features (e.g., Toolset::slug(), Toolset::randomString()).
   • Source Code: Browse src/ToolsetServiceProvider.php to see registered bindings.

Implementation Patterns

Common Workflows

1. String Manipulation

   // Slugify a string
   $slug = Toolset::slug('Hello World!');
   
   // Random string generation
   $token = Toolset::randomString(32);
   

2. Data Transformation

   // Convert snake_case to camelCase
   $camel = Toolset::snakeToCamel('user_name');
   
   // Array flattening
   $flat = Toolset::flatten(['a' => ['b' => 1]]);
   

3. File/Path Handling

   // Get relative path
   $relative = Toolset::relativePath('/var/www', '/var/www/project/file.txt');
   
   // Ensure trailing slash
   $path = Toolset::ensureTrailingSlash('/var/www');
   

4. Integration with Laravel

   • Service Container: Bind custom extensions:

     $this->app->extend('toolset', function ($toolset) {
         $toolset->extend('customMethod', function () {
             return 'Custom logic';
         });
         return $toolset;
     });
     

   • Blade Directives: Register helpers for views:

     Toolset::blade()->directive('uuid', function () {
         return "<?php echo \\Achinon\\Toolset\\Toolset::uuid(); ?>";
     });
     

5. Testing Use the facade in tests for consistent utility methods:

   public function testSlugGeneration()
   {
       $this->assertEquals('hello-world', Toolset::slug('Hello World!'));
   }
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • If the package uses similar method names (e.g., str()), ensure no conflicts with Laravel’s Str helper.
   • Fix: Prefix calls or alias the facade:

     use Toolset as ToolsetUtils;
     

2. Undefined Methods

   • The package may not throw clear errors for non-existent methods. Use method_exists():

     if (method_exists(Toolset::getFacadeRoot(), 'someMethod')) {
         Toolset::someMethod();
     }
     

3. Configuration Overrides

   • If the package supports config (e.g., config/toolset.php), ensure defaults align with your project:

     'default_locale' => 'en_US', // Override if needed
     

Debugging Tips

1. Inspect the Facade Root Dump the underlying class to explore methods:

   dd(method_get_properties(new \Achinon\Toolset\Toolset()));
   

2. Check for Static Methods Some utilities might be static. Access them directly:

   \Achinon\Toolset\Toolset::staticMethod();
   

3. Extension Points

   • Custom Methods: Extend the facade via the service provider:

     $toolset->extend('myMethod', function () {
         return 'Extended!';
     });
     

   • Override Defaults: Publish config if available:

     php artisan vendor:publish --tag=toolset-config
     

Performance Notes

• Avoid Facade Calls in Loops: Cache results if methods are called repeatedly:

  $cachedSlug = cache()->remember('slug_key', now()->addHours(1), function () {
      return Toolset::slug($input);
  });
  

• Memory Usage: For large data transformations (e.g., flatten()), test with sample datasets first.

Undocumented Features

• Dynamic Facade Methods: Some packages support dynamic method calls. Test:

  if (Toolset::respondsTo('unknownMethod')) {
      // Safe to call
  }