Phpwind Laravel Package

Getting Started

• composer require medz/phpwind — first check the composer.json in the repo for its PHP version floor. This is generator-era code, so confirm it installs cleanly on your runtime before you build on it.
• Require vendor/autoload.php and confirm the namespace from the README / src/. The package is small; read the main Wind class end-to-end before writing anything. That file is the API.
• First use case: flatten a callback/Promise chain into linear code. You wrap a Generator function, yield each async step, and let the runner drive the continuations.

use Medz\Wind\Wind; // verify namespace against the repo

$wind = new Wind();

$result = $wind->run(function () {
    $a = yield $someAsyncStep();      // suspension point
    $b = yield $anotherStep($a);      // resumes when $a resolves
    return $b;                        // returned to the runner's caller
});

Whether the entry point is static or instance-based is version-dependent — the shape is the same either way: a factory takes a Generator callable and returns a driver handle you can inspect for completion, errors, or results.

Implementation Patterns

• Linear async pipelines. Every yield is a suspension point; the runner resumes the generator when the yielded value resolves. Use this to collapse nested callbacks in HTTP clients, DB drivers, or queue consumers into something that reads top-to-bottom.
• Composition of small flows. Keep generator functions narrow and single-purpose, then yield one flow from another as a sub-step. This is the main testability win — each unit can be driven standalone without the parent.
• Adapters at the boundary. Wrap every legacy callback API into a yieldable in one thin adapter file. Do this once per library rather than scattering generator syntax across your domain logic; it keeps the async model swappable.
• Error handling inside the generator. Use try/catch around suspension points so exceptions thrown by a yielded operation propagate through your flow instead of escaping into the runner loop where you lose context.
• Keep the runner at the edge. Drive flows from controllers, artisan commands, or workers; keep domain code as plain functions or isolated flows. If you later migrate to Fibers or an event loop, only the edge changes.

Gotchas and Tips

• It is a flow-control primitive, not a framework. No routing, HTTP, DI container, or ORM. The 180-star count reflects niche scope, not hidden depth. Budget accordingly.
• Maintenance risk is real. A score of 2.23 on an aging codebase means pin an exact version in composer.json and skim the source (it's small) before relying on it. Check open issues for PHP 8.x compatibility and generator edge cases before starting.
• Generators do not run on call. A function containing yield returns a Generator immediately and executes nothing. Forgetting the runner call is the single most common silent failure — no error, no output, no side effects.
• Keyed yields are not free. yield $key => $value may be interpreted differently than a plain yield depending on the runner's continuation handling. Verify against the source before using keys as labels.
• Debugging points at the wrong place. Stack traces land on the generator, not your original call site. Tag each flow with an ID and log at suspension points; a small wrapper around run() pays for itself the first time a chain hangs.
• Extension belongs beside the runner. Custom dispatchers, timers, and adapters should live next to the Wind class, not in application code — that's the seam intended for extension and the one place you can safely patch behavior.
• Do not half-migrate. Decide up front whether Wind drives your entire async surface or exactly one leaf worker. Mixed paradigms in the same code path are where this class of library gets painful fast.