Generalutil Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require abo/generalutil
   

   Publish the config (if available) with:

   php artisan vendor:publish --provider="Abo\Generalutil\GeneralutilServiceProvider"
   

2. First Use Case The package appears to be a utility library, so start by exploring the core classes in src/. For example, if it includes common helpers like StringUtil, ArrayUtil, or DateUtil, test them immediately:

   use Abo\Generalutil\Helpers\StringUtil;
   
   $sanitized = StringUtil::sanitizeInput("user_input");
   $slug = StringUtil::toSlug("Example Title");
   

3. Where to Look First

   • Namespace: Check src/ for core classes (e.g., Helpers/, Services/).
   • Facade: If a facade exists (e.g., Generalutil), use it for quick access:

     use Abo\Generalutil\Facades\Generalutil;
     

   • Config: Review config/generalutil.php for customizable settings (if published).

Implementation Patterns

Common Workflows

1. Helper Methods in Controllers/Blades Use utility methods directly in views or controllers for repetitive tasks:

   // In a controller
   $formattedDate = DateUtil::formatToReadable($date);
   return view('page', ['date' => $formattedDate]);
   
   // In a Blade template
   @php
     $truncated = StringUtil::truncate($longText, 50);
   @endphp
   <p>{{ $truncated }}</p>
   

2. Service Layer Integration Wrap utility logic in a service class to maintain separation of concerns:

   namespace App\Services;
   
   use Abo\Generalutil\Helpers\ArrayUtil;
   
   class DataTransformer {
       public function transform($data) {
           return ArrayUtil::flatten($data);
       }
   }
   

3. Middleware for Global Utilities Apply utility logic globally via middleware (e.g., sanitizing input):

   namespace App\Http\Middleware;
   
   use Abo\Generalutil\Helpers\StringUtil;
   use Closure;
   
   class SanitizeInput {
       public function handle($request, Closure $next) {
           $request->merge([
               'clean_input' => StringUtil::sanitizeInput($request->input)
           ]);
           return $next($request);
       }
   }
   

4. Model Observers/Accessors Use utilities in model events or accessors:

   // In a model
   public function getFormattedNameAttribute() {
       return StringUtil::capitalize($this->name);
   }
   

Integration Tips

• Dependency Injection: Prefer constructor injection for utilities in services:

  public function __construct(private StringUtil $stringUtil) {}
  

• Testing: Mock utilities in tests to isolate logic:

  $this->mock(Abo\Generalutil\Helpers\StringUtil::class)
       ->shouldReceive('sanitizeInput')
       ->andReturn('mocked');
  

• Performance: Cache results of expensive utility operations (e.g., slug generation) if used frequently:

  $slug = Cache::remember("slug_{$title}", 3600, fn() => StringUtil::toSlug($title));
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts The package may lack a unique namespace prefix (e.g., Abo\Generalutil). If you encounter conflicts:

   • Use fully qualified class names:

     \Abo\Generalutil\Helpers\ArrayUtil::merge(...);
     

   • Alias namespaces in composer.json:

     "autoload": {
       "psr-4": {
         "App\\": "app/",
         "Abo\\": "vendor/abo/generalutil/src/"
       }
     }
     

2. Undocumented Methods The package’s README is minimal. Use IDE autocompletion or php artisan ide-helper:generate to discover available methods:

   composer require --dev barryvdh/laravel-ide-helper
   php artisan ide-helper:generate
   

3. Configuration Assumptions If the package expects config values (e.g., default timezones or sanitization rules), ensure they’re set in config/generalutil.php:

   'sanitization' => [
       'allowed_tags' => '<p><a><strong>',
   ],
   

4. Thread Safety If utilities modify shared state (e.g., static caches), ensure thread safety in queue workers or scheduled jobs:

   // Avoid:
   static::cache($data); // Risky in concurrent environments
   
   // Prefer:
   Cache::put("key", $data, $ttl);
   

Debugging Tips

1. Log Utility Outputs Add debug logs to trace utility behavior:

   \Log::debug('Sanitized input:', ['output' => StringUtil::sanitizeInput($input)]);
   

2. Check for Deprecated Methods If the package is updated, deprecated methods may break code. Use:

   composer show abo/generalutil
   

   to check for recent changes.

3. Fallback for Missing Methods Handle cases where a utility method might not exist:

   if (method_exists(StringUtil::class, 'toSlug')) {
       $slug = StringUtil::toSlug($title);
   } else {
       $slug = Str::slug($title); // Fallback to Laravel's Str
   }
   

Extension Points

1. Custom Utility Classes Extend existing utilities to add domain-specific logic:

   namespace App\Utils;
   
   use Abo\Generalutil\Helpers\StringUtil;
   
   class AppStringUtil extends StringUtil {
       public static function toAppSlug($input) {
           return parent::toSlug($input) . '-app';
       }
   }
   

2. Service Provider Binding Override default bindings in your AppServiceProvider:

   public function register() {
       $this->app->bind(
           \Abo\Generalutil\Contracts\StringSanitizer::class,
           App\Utils\AppStringSanitizer::class
       );
   }
   

3. Publish and Modify Views/Configs Publish and customize the package’s assets:

   php artisan vendor:publish --tag=generalutil-views
   php artisan vendor:publish --tag=generalutil-config
   

4. Event Listeners for Utilities Trigger events when utilities perform critical actions (e.g., input sanitization):

   event(new InputSanitized($input, $output));
   

   Listen in EventServiceProvider:

   protected $listen = [
       InputSanitized::class => [
           \App\Listeners\LogSanitization::class,
       ],
   ];