Skip to content

Latest commit

 

History

History
239 lines (183 loc) · 6.88 KB

README.md

File metadata and controls

239 lines (183 loc) · 6.88 KB

Stream

Pipe-native stream functions for PHP 8.5+. Curried, lazy, zero-wrapper.

use function Stann\Stream\{filter, map, take, toArray};

$result = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    |> filter(fn(int $n) => $n % 2 === 0)
    |> map(fn(int $n) => $n * 10)
    |> take(3)
    |> toArray();

// [20, 40, 60]

Philosophy

No Collection object. No method chaining. Just pure functions designed for the PHP 8.5 pipe operator (|>).

Each function is curried: it takes its configuration and returns a Closure that accepts an iterable. The pipe operator does the wiring.

data |> transform(config) |> transform(config) |> terminator(config)
  • Data-last — like Ramda (JS) or Elixir pipes
  • Lazy by default — transformations return Generators, nothing executes until consumed
  • Zero dependency — just PHP 8.5

Installation

composer require stann/stream

Requires PHP 8.5+ (for the pipe operator |>).

Quick Start

use function Stann\Stream\{filter, map, take, toArray};

// Simple pipeline
$emails = $users
    |> filter(fn(User $u) => $u->isActive())
    |> map(fn(User $u) => $u->email)
    |> map(trim(...))
    |> toArray();

// Lazy evaluation — only 100 elements processed, not all
$result = $hugeDataset
    |> filter(fn($row) => $row['status'] === 'ok')
    |> map(fn($row) => transform($row))
    |> take(100)
    |> toArray();

API

Full documentation with signatures and examples: docs/API.md

Transformations

Lazy (Generator-based) unless noted as blocking.

  • map — Apply a callback to each element
  • filter — Keep elements matching a predicate (without callback: remove falsy values)
  • flatMap — Map then flatten one level
  • flatten — Flatten one level of nested iterables
  • take — Take the first N elements
  • takeWhile — Take while predicate holds
  • skip — Skip the first N elements
  • skipWhile — Skip while predicate holds
  • chunk — Split into fixed-size chunks
  • groupBy — Group by key function (blocking)
  • sortBy — Sort by key function (blocking)
  • unique — Remove duplicates
  • zip — Combine two iterables into pairs
  • concat — Append another iterable
  • enumerate — Pair elements with their index
  • scan — Running fold (intermediate values)
  • reverse — Reverse elements (blocking)
  • keys — Extract keys
  • values — Extract values
  • pluck — Extract a property/key from each element
  • tap — Side effect without altering the stream

Terminators

Consume the iterable and return a final value.

  • toArray — Convert to array
  • reduce — Fold into a single value
  • first — First element (optionally matching predicate)
  • last — Last element (optionally matching predicate)
  • count — Count elements
  • sum — Sum elements
  • min — Minimum element
  • max — Maximum element
  • join — Join into a string
  • contains — Check if value exists
  • every — All match predicate?
  • some — Any match predicate?
  • partition — Split into two arrays by predicate
  • each — Consume with side effect (void)

Patterns

Pagination

$page3 = $items
    |> sortBy(fn(Item $i) => $i->name)
    |> skip(($page - 1) * $perPage)
    |> take($perPage)
    |> toArray();

Batch Processing

$items
    |> chunk(50)
    |> map(fn(array $batch) => processBatch($batch))
    |> flatMap(fn(array $results) => $results)
    |> toArray();

Aggregation

$byCountry = $customers
    |> filter(fn(Customer $c) => $c->revenue > 1000)
    |> groupBy(fn(Customer $c) => $c->country)
    |> map(fn(array $group) => $group |> sum(fn($c) => $c->revenue));

Price Calculation

$total = $prices
    |> zip($quantities)
    |> map(fn(array $pair) => $pair[0] * $pair[1])
    |> sum();

Running Totals

$runningTotal = $transactions
    |> map(fn(Transaction $t) => $t->amount)
    |> scan(fn(float $acc, float $v) => $acc + $v, 0.0)
    |> toArray();

Extending with Custom Steps

The pipe is open by design. Any function that takes an iterable and returns an iterable (or a final value) fits right in — no interface to implement, no class to extend.

Without parameters — use (...)

function removeNulls(iterable $items): Generator {
    foreach ($items as $value) {
        if ($value !== null) {
            yield $value;
        }
    }
}

$data |> removeNulls(...) |> map(fn($v) => $v * 2) |> toArray();

With parameters — use currying

function olderThan(int $minAge): Closure {
    return static function (iterable $items) use ($minAge): Generator {
        foreach ($items as $user) {
            if ($user->age >= $minAge) {
                yield $user;
            }
        }
    };
}

$users
    |> olderThan(18)
    |> filter(fn(User $u) => $u->isActive())
    |> map(fn(User $u) => $u->email)
    |> map(trim(...))
    |> toArray();

Both approaches mix naturally with the library's functions. The only rule: the pipe expects a single-argument callable (iterable → something).

How It Works

Every function follows the same pattern:

function map(callable $fn): Closure
{
    return static function (iterable $items) use ($fn): Generator {
        foreach ($items as $key => $value) {
            yield $key => $fn($value, $key);
        }
    };
}
  1. Takes configuration (the callback, size, etc.)
  2. Returns a Closure that accepts iterable
  3. The pipe operator passes the data

This is currying — you fix the transformation, and the pipe injects the data.

Lazy vs Blocking

Lazy (Generator) Blocking (array)
map, filter, flatMap, flatten, take, takeWhile skip, skipWhile, chunk, zip, concat, enumerate scan, unique, keys, values, pluck, tap sortBy, groupBy, reverse

Blocking operations need all data upfront (you can't sort without seeing everything). Lazy operations process elements one by one.

Development

composer install
composer test          # PHPUnit
composer phpstan       # Static analysis (level 8)
composer cs-check      # Code style check
composer cs-fix        # Auto-fix code style

License

MIT