README

A Laravel/PHP Package for Minimizing Collection/Array Iterations - optimized for large datasets (100,000+ records).

📊 Performance Benchmarks

Real-world performance tests show significant improvements with large datasets:

⚠️ Performance Warning

This package is optimized for large datasets. It provides significant performance improvements when:

• Processing 100,000+ records
• Chaining 2-3+ operations (filter, map, reject, etc.)
• Running batch jobs or data processing tasks

For small datasets (< 50,000 records), standard PHP array functions or Laravel Collections will be faster due to lower overhead.

Installation

Install the package via composer:

composer require hassan/one-loop

Usage

Basic Example

$users = App\User::all();

$ids = one_loop($users)->reject(static function ($user) {
    return $user->age < 20;
})
->map(static function ($user) {
    return $user->id;
})
->apply();

🆕 New Features in v2.0

Early Exit with limit() / take()

Stop processing once you have enough results:

// Get first 100 active users
$users = one_loop($allUsers)
    ->filter(fn($user) => $user->active)
    ->limit(100)
    ->apply();

// Alias: take()
$users = one_loop($allUsers)
    ->filter(fn($user) => $user->active)
    ->take(100)
    ->apply();

Extract Properties with pluck()

// Pluck by property name
$emails = one_loop($users)
    ->pluck('email')
    ->apply();

// Pluck with callback
$fullNames = one_loop($users)
    ->pluck(fn($user) => $user->first_name . ' ' . $user->last_name)
    ->apply();

Remove Duplicates with unique()

// Unique values
$uniqueDepartments = one_loop($employees)
    ->pluck('department')
    ->unique()
    ->apply();

// Unique by key
$uniqueUsers = one_loop($users)
    ->unique('email')
    ->apply();

Group Items with groupBy()

// Group by property
$byDepartment = one_loop($employees)
    ->groupBy('department')
    ->apply();

// Group by callback
$byAgeGroup = one_loop($users)
    ->groupBy(function($user) {
        if ($user->age < 30) return 'young';
        if ($user->age < 50) return 'middle';
        return 'senior';
    })
    ->apply();

Conditional Operations with when()

$shouldFilterActive = true;

$result = one_loop($users)
    ->when($shouldFilterActive, function($loop) {
        $loop->filter(fn($user) => $user->active);
    })
    ->map(fn($user) => $user->id)
    ->apply();

Laravel Collection Integration

OneLoop automatically integrates with Laravel Collections:

use Illuminate\Support\Collection;

// Use on any Collection
$result = User::all()
    ->oneLoop()
    ->filter(fn($user) => $user->active)
    ->map(fn($user) => $user->id)
    ->apply();

🎓 Available Methods

Filtering

• filter(callable $callback) - Keep items that match condition
• reject(callable $callback) - Remove items that match condition

Transformation

• map(callable $callback) - Transform each item
• pluck(string|callable $value) - Extract specific property

Uniqueness & Grouping

• unique(?string|callable $key = null) - Remove duplicates
• groupBy(string|callable $groupBy) - Group by key or callback

Limiting

• limit(int $limit) - Limit results (early exit)
• take(int $count) - Alias for limit()

Conditional

• when(bool $condition, callable $callback, ?callable $default = null) - Conditional operations

Execution

• apply() - Execute all queued operations and return results

📊 When to Use OneLoop

✅ Perfect For:

• Large datasets (100K+ records)
• Batch processing jobs
• ETL operations
• Data migrations
• Complex filtering with 2-3+ operations
• Report generation
• Product catalog filtering (e-commerce)
• Customer segmentation (marketing)

❌ Not Ideal For:

• Small datasets (< 50K records)
• Single operation (just one filter or map)
• Real-time web requests with small result sets
• When microseconds matter with tiny datasets

🎯 Real-World Example

// E-commerce: Process large product catalog
$products = Product::all()  // 500,000 products
    ->oneLoop()
    ->filter(fn($p) => $p->active)
    ->reject(fn($p) => $p->stock <= 0)
    ->when($categoryFilter, fn($loop) => 
        $loop->filter(fn($p) => in_array($p->category_id, $categoryFilter))
    )
    ->map(fn($p) => [
        'id' => $p->id,
        'name' => $p->name,
        'price' => $p->price * 0.9  // 10% discount
    ])
    ->limit(1000)
    ->apply();

// Result: 35% faster than standard operations!

🧪 Testing

composer test

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔒 Security

If you discover any security related issues, please email hello@hassan-ali.me instead of using the issue tracker.

📜 License

The MIT License (MIT). Please see License File for more information.

🙏 Credits

• Hassan Ali
• All Contributors