Fast Set Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require toflar/fast-set
   

   Register the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       Toflar\FastSet\FastSetServiceProvider::class,
   ],
   

2. Basic Usage Create a precompiled set from an array:

   use Toflar\FastSet\Facades\FastSet;
   
   $set = FastSet::create(['apple', 'banana', 'cherry']);
   $exists = $set->contains('banana'); // Returns true instantly
   

3. First Use Case Optimize a Laravel request filter or validation rule:

   $allowedRoles = FastSet::create(['admin', 'editor', 'viewer']);
   if ($allowedRoles->contains(auth()->user()->role)) {
       // Proceed with elevated permissions
   }
   

Implementation Patterns

Common Workflows

1. Precompiled Sets for Performance Use in high-frequency checks (e.g., route middleware, API rate limiting):

   $rateLimitedIps = FastSet::create(explode(',', config('rate_limit.ips')));
   if ($rateLimitedIps->contains(request()->ip())) {
       abort(429);
   }
   

2. Caching Layer Integration Cache precompiled sets to avoid recompilation:

   $cachedSet = Cache::remember('user_roles_set', now()->addHour(), function () {
       return FastSet::create(User::pluck('role')->unique()->toArray());
   });
   

3. Laravel Collections Extension Add a toFastSet() method to collections:

   // In a Collection macro (e.g., in AppServiceProvider)
   collect(['a', 'b', 'c'])->macro('toFastSet', function () {
       return FastSet::create($this->all());
   });
   

Integration Tips

• Database Results: Convert Eloquent collections to sets for fast lookups:

  $activeUserIds = User::where('active', true)->pluck('id')->toFastSet();
  

• Blade Directives: Create a @set directive for template checks:

  // In AppServiceProvider
  Blade::directive('set', function ($expression) {
      return "<?php echo (Toflar\FastSet\Facades\FastSet::create({$expression})->contains(" . $expression[1] . ")) ? 'true' : 'false'; ?>";
  });
  

• Event Listeners: Use for fast event subscriber checks:

  $subscribers = FastSet::create(config('event.subscribers'));
  if ($subscribers->contains($eventName)) {
      // Dispatch event
  }
  

Gotchas and Tips

Pitfalls

1. Memory vs. Speed Tradeoff

   • Precompiled sets consume ~3x more memory than PHP arrays but offer O(1) lookup time.
   • Avoid creating sets for small datasets (<100 items); use native in_array() instead.

2. Immutable After Creation

   • Sets are immutable. To modify, recreate:

     $set = $set->merge(['new_item']); // Returns a new set
     

3. Serialization Issues

   • Sets cannot be serialized/JSON-encoded directly. Use getArrayCopy():

     $array = $set->getArrayCopy();
     

4. Case Sensitivity

   • By default, sets are case-sensitive. For case-insensitive checks:

     $set = FastSet::create(['Apple', 'Banana'], true); // Second arg = case-insensitive
     

Debugging

• Verify Compilation Check if the set is properly compiled with:

  $set->isCompiled(); // Returns true if optimized
  

• Memory Leaks Use unset() to free memory when done:

  unset($largeSet);
  

Extension Points

1. Custom Hashing Override hashing for complex objects:

   FastSet::hash(function ($item) {
       return md5(serialize($item));
   });
   

2. Lazy Loading Create a proxy set that loads data on first access:

   $proxy = new class($dataLoader) implements \ArrayAccess {
       public function offsetExists($offset) {
           return FastSet::create($this->loadData())->contains($offset);
       }
       // ...
   };
   

3. Laravel Cache Store Extend the FastSet class to support cache storage:

   class CachedFastSet extends \Toflar\FastSet\FastSet {
       public function __construct(string $cacheKey, array $data = []) {
           parent::__construct($data);
           Cache::put($cacheKey, $this);
       }
   }