Util Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require ardent/util-bundle
   

   Register the bundle in config/bundles.php:

   Ardent\UtilBundle\ArdentUtilBundle::class => ['all' => true],
   

2. First Use Case: String Manipulation Use the StringHelper for common string operations:

   use Ardent\UtilBundle\Helper\StringHelper;
   
   $cleaned = StringHelper::slugify('Hello World!'); // 'hello-world'
   $truncated = StringHelper::truncate('Long string...', 10); // 'Long strin...'
   

3. Where to Look First

   • Helper Classes: Explore src/Helper/ for utilities like ArrayHelper, DateHelper, StringHelper, etc.
   • Service Container: Check src/Service/ for reusable services (e.g., CacheService, LoggerService).
   • Traits: Review src/Traits/ for reusable logic (e.g., ArrayTrait, CollectionTrait).

Implementation Patterns

Common Workflows

1. String Operations Use StringHelper for consistent string formatting across projects:

   // Slugify, truncate, or sanitize strings
   $slug = StringHelper::slugify($userInput);
   

2. Array/Collection Manipulation Leverage ArrayHelper for deep array operations:

   // Get nested array value with a fallback
   $value = ArrayHelper::get($array, 'path.to.value', 'default');
   
   // Merge arrays recursively
   $merged = ArrayHelper::merge($array1, $array2);
   

3. Date/Time Handling Use DateHelper for timezone-aware operations:

   // Convert a string to a Carbon instance
   $date = DateHelper::parse('2023-12-31', 'Europe/Amsterdam');
   
   // Format dates consistently
   $formatted = DateHelper::format($date, 'Y-m-d H:i:s');
   

4. Service Integration Inject CacheService or LoggerService into controllers/services:

   public function __construct(private CacheService $cache) {}
   
   public function getCachedData() {
       return $this->cache->get('key', function() {
           return $this->fetchExpensiveData();
       });
   }
   

5. Traits for Reusability Extend classes with traits to avoid duplication:

   use Ardent\UtilBundle\Traits\ArrayTrait;
   
   class MyService {
       use ArrayTrait;
   
       public function processData(array $data) {
           return $this->arrayGet($data, 'key', []);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The bundle uses Ardent\UtilBundle namespace. Ensure no conflicts with your project’s namespaces.
   • Fix: Use fully qualified class names or aliases in config/app.php.

2. Carbon Dependency

   • Some helpers (e.g., DateHelper) rely on nesbot/carbon. Ensure it’s installed:

     composer require nesbot/carbon
     

3. Service Container Binding

   • Services like CacheService are bound to the container but may require configuration (e.g., cache driver).
   • Tip: Override bindings in config/services.php if needed:

     'cache.driver' => env('CACHE_DRIVER', 'array'),
     

4. Trait Method Conflicts

   • Traits like ArrayTrait may override core PHP methods (e.g., arrayGet). Test thoroughly in your project.

Debugging Tips

1. Check Helper Methods

   • Use dd() or dump() to inspect helper outputs:

     dump(StringHelper::slugify('Test!')); // Debug slugification
     

2. Cache Service Issues

   • If CacheService fails, verify the cache driver is configured in .env:

     CACHE_DRIVER=file
     

3. String Sanitization

   • StringHelper::sanitize() may strip unexpected characters. Test edge cases:

     StringHelper::sanitize('User <script>input</script>'); // 'User input'
     

Extension Points

1. Custom Helpers

   • Extend existing helpers by creating child classes:

     class CustomStringHelper extends StringHelper {
         public static function customSlugify($string) {
             return parent::slugify($string) . '-custom';
         }
     }
     

2. Add New Traits

   • Create project-specific traits in app/Traits/ and reuse them across services.

3. Override Services

   • Bind custom implementations in AppServiceProvider:

     $this->app->bind(CacheService::class, function($app) {
         return new CustomCacheService();
     });
     

4. Configuration

   • Override default settings via config/packages/ardent_util.yaml:

     string:
         separator: '_' # Override slugify separator