DEV Community: Nana Axel

Fan-out on read vs fan-out on write: choosing the right trade-off for a dynamic feed

Nana Axel — Tue, 29 Sep 2026 17:51:42 +0000

This post will talk about how every feed in our social medias are designed. From the user’s side, a feed looks simple: open a page, see recent updates, keep scrolling, infinitely.

But behind that list, there is an improtant design decision: when should the system assemble each person’s feed?
It can do most of the work when someone publishes a post, or wait until a reader opens their feed. Those approaches are usually called fan-out on write and fan-out on read.

The right choice is not picking one, as each moves work to a different part of the system, and the better fit depends on how often people post, how often feeds are read, and how unevenly followers are distributed.

First, what is being fanned out?

Let's say Alice publishes a post and 200 people follow her. The system needs to make that post available in those 200 people’s feeds. It could:

add a reference to Alice’s post to each follower’s feed when she publishes it; or
leave the post in Alice’s own collection and find it when each follower opens their feed.

The post itself remains in one canonical record either way. A precomputed feed often stores post IDs or references, rather than a full duplicate of every post. So the design question is not whether a feed needs aggregation (it always needs it), it is when that aggregation happens.

Fan-out on write: prepare the feed ahead of time

Fan-out on write needs a prerequisite: each user has its own feed collection, referencing followed users' posts. That feed is persisted in the storage that suits most your use case (database, cache, memory). When a user publishes a post, the system creates new feed entries for its followers:

publish(post):
    storeCanonicalPost(post)
    for follower in followersOf(post.author):
        addReferenceToFeed(follower, post.id)

When a reader opens their feed, the system retrieves a list that is already assembled. That makes the read path easier to keep fast and predictable. This method is optimal when people read feeds frequently and most authors have a manageable amount of followers.

On the other hand, the cost moves to publishing. One post by an account with 200 followers may create around 200 feed entries, same for a post by an account with millions of followers. It also do work for followers who rarely open the feed. And when a post is deleted or access changes, every stored reference may need to be removed or checked against current permissions.

In real production systems, those issues are mitigated by making the fan-out asynchronous. The post is stored first, then background workers create references to followers’ feeds. This keeps a large delivery job off the request that publishes the post, with the cost of a briefly outdated feed.

Fan-out on read: assemble the feed when it is requested

With fan-out on read, publishing stores the post once. When someone opens their feed, the system fetches recent posts from the accounts they follow, then merges and ranks the results:

getFeed(reader):
    authors = followedAuthors(reader)
    candidates = fetchRecentPosts(authors)
    return rankAndLimit(candidates)

This avoids all the costs explored in fan-out on write approach. It can be a good fit when writes are frequent, many followers are inactive, or ranking rules change often.

But the cost is non-negligible, since the work appears on the read path instead. A reader who follows many accounts may require the system to fetch and combine a large set of recent posts for each request. That can increase database load and make latency less predictable.

The implementation matters here. “One query per followed account” is not the only possible design; indexes, batching, caching, and the way data is partitioned all affect the cost. But the system still has to gather enough candidate posts to build a useful feed at request time.

The trade-off

	Fan-out on write	Fan-out on read
Main work happens	When a post is published	When a feed is requested
Publish cost	Grows with follower count	Usually stays close to one canonical write
Feed read	Starts from a prepared list	Must gather and combine candidates
Storage	More feed references to maintain	Fewer precomputed feed entries
Useful when	Reads are frequent and audiences are manageable	Writes are frequent, audiences are uneven, or ranking changes often
Main pressure	Large authors create write spikes	Large follow lists make reads more expensive

This table describes where the work moves. It doesn’t guarantee a particular latency or storage cost. Those depend on the data model, indexes, caching, ranking, and delivery requirements.

Why many systems use a hybrid

Follower counts tend to be uneven. Most authors may have a modest audience, while a small number have very large ones. That makes a hybrid practical:

Fan out posts from ordinary accounts on write.
Keep posts from very large accounts in their own collections.
Fetch those high-follower posts when a reader opens their feed.
Merge both sets of candidates before returning the feed.

The hybrid approach avoids pushing every post to a huge audience immediately, while also avoiding a read-time fetch from every single followed account. There is no universal follower-count threshold. The useful cutoff depends on your workload: how frequently authors post, how often their followers read, how much read latency you can afford, and how much asynchronous write work your system can absorb.

Ask questions before choosing

What is the read-to-write ratio? If feeds are opened far more often than posts are published, precomputing some work may pay off.
How skewed are follower counts? A few exceptionally large accounts can make a pure write-time strategy costly.
How fresh must the feed be? Asynchronous fan-out can introduce a short delay; this is typically accpetable for large feeds.
How often does ranking change? If feed order depends on changing relevance scores, rebuilding stored feeds can become part of the cost.
How do deletes and permissions work? This can be tricky, since a feed entry should not make content visible after the underlying post or access rights have changed.

I recently worked on a project where such decisions were required, since the project is new an not yet extensively used, we selected fan-out on read while we collect enough metrics to evaluate when and how to optimize: measure where the work happens, then optimize the bottleneck the product actually has.

What would you choose for a feed where most accounts have a small audience, but a few have millions of followers? Let's discuss in comments!

If your mobile app decides which step comes next, your backend is trusting the client, and this won't scale. This is why at Zeney Pay, we moved to a backend-authored state machine. Let's explore the design decisions and the trade-offs we accepted.

Nana Axel — Mon, 28 Sep 2026 12:48:50 +0000

Nana Axel

Sep 26

I built a generic multi-step flow engine on top of Laravel controllers

#php #laravel #api #architecture

12 min read

I built a generic multi-step flow engine on top of Laravel controllers

Nana Axel — Sat, 26 Sep 2026 12:27:41 +0000

At Zeney Pay we build a mobile app for cross-border money transfers and real-time currency conversion. A fintech backend is mostly flows: sign-in with 2FA, registration, KYC, "forgot my PIN", setting up a transaction PIN, sending money. None of them fit in a single HTTP request.

For a while we handled them the way most teams do, and it went badly. This post covers what went wrong, how we changed our thinking, the design decisions behind the result, and the package that came out of it: na2axl/laravel-api-flow.

How it went wrong

Our flows were spread out in two ways:

On the backend, one flow was split across several controllers. AuthController@login, OtpController@verify, PinController@check... Each endpoint had to work out for itself whether the caller had actually gone through the earlier steps.
On the frontend, the mobile app held the rest. It decided which screen came next, when to skip the OTP screen, and what "back" meant.

This gave us several sources of truth for the same business process. Changing the order of two steps meant a backend deploy and a mobile release, with app store review in between. Old app versions kept following the old order. Each "is the user allowed to call this now?" check was written by hand, a little differently each time, and sometimes forgotten.

The turning point came when I saw what we were really doing: we were fitting business requirements into technical constraints. You do need an HTTP controller to handle a request. But the requests weren't standalone. They were transitions in a bigger state machine, and the backend had to be the only party that processes those transitions and decides whether they're valid.

Starting with sign-in

We started with authentication because it's the flow where getting it wrong hurts most. Here is sign-in as the business sees it:

Even this "simple" login has branches. The user may or may not have 2FA. 2FA can be an SMS OTP or a TOTP app. A user who lost their device can use a recovery code. Some users have to change their PIN before they get a session. Some never set a transaction PIN and get handed off to a different flow. If a client can reach check-pin without passing check-mfa, you've built a 2FA bypass.

Before writing code, we designed the API. For the backend to really be the source of truth, it had to meet five criteria:

Knowledge of the steps. The backend knows every step and how to process it.
Knowledge of the position. At any moment the backend knows where the machine currently is.
Memory. The state collected along the way (who is signing in, whether 2FA passed, which OTP was sent) lives across steps, on the server.
Navigation. For each step, the frontend knows which steps it can go to next and which earlier steps it can go back to.
Security. The backend rejects any wrong or illegal transition. It does this by construction, not through checks someone has to remember to write.

Each of these criteria led to a concrete design decision.

The package in 60 seconds

This is a complete flow:

use Na2axl\LaravelApiFlow\FlowController;
use Na2axl\LaravelApiFlow\FlowResponse;
use Na2axl\LaravelApiFlow\FlowState;

class SignupFlowController extends FlowController
{
    public const FLOW_ID = 'signup';

    protected string $flowStateClass = SignupState::class;
    protected string $flowId = self::FLOW_ID;
    protected ?int $staleTimeInMinutes = 15;

    public function stepInitiate(): FlowResponse
    {
        return $this->initiateFlow();
    }

    public function stepSetEmail(SetEmailRequest $request): FlowResponse
    {
        $this->validateStep($request->flowKey(), 'set-email'); // 410 if expired, 409 if illegal
        $this->appendState($request->flowKey(), ['email' => $request->validated('email')]);

        return $this->answer($request->flowKey(), 'set-email');
    }

    public function stepSetPlan(SetPlanRequest $request): FlowResponse
    {
        $this->validateStep($request->flowKey(), 'set-plan');
        $this->appendState($request->flowKey(), ['plan' => $request->validated('plan')]);

        return $this->answer($request->flowKey(), 'set-plan');
    }

    protected function nextSteps(string $current, FlowState $state): array
    {
        return match ($current) {
            'initiate'  => ['set-email'],
            'set-email' => ['set-plan'],
            'set-plan'  => [], // empty = the flow is finished, state is discarded
            default     => [],
        };
    }

    protected function backSteps(string $current, FlowState $state): array
    {
        return $current === 'set-plan' ? ['set-email'] : [];
    }

    protected function onRewind(string $step, FlowState $state): void
    {
        if ($step === 'set-email') {
            $state->plan = null; // re-answering the email discards the plan
        }
    }
}

Route::flow('signup', SignupFlowController::class);

Every step follows the same three beats: validateStep() -> do the work -> answer(). The client only ever sees this:

POST /signup/set-email  { "flow_key": "01J8Q0ZK...", "email": "a@b.c" }
-> 200 { "data": {}, "next_steps": ["set-plan"], "back_steps": [] }

POST /signup/set-plan  (jumping ahead on a fresh flow)
-> 409 { "message": "Unexpected step.", "code": "FLOW_UNEXPECTED_STEP" }

POST /signup/set-email  (stale flow key)
-> 410 { "message": "Flow expired.", "code": "FLOW_EXPIRED" }

Now for the reasoning behind each of those choices.

The design decisions (and what we didn't pick)

1. The flow is a controller, and each step is a real route

Each public stepXxx method is a step. Route::flow() reflects over the controller and registers one route per step: stepInitiate becomes GET /{prefix}/initiate, and every other stepFooBar becomes POST /{prefix}/foo-bar, named flow.{prefix}.foo-bar.

Route::flow('sign-in', SignInFlowController::class);
// GET  /sign-in/initiate
// POST /sign-in/authenticate
// POST /sign-in/check-mfa
// POST /sign-in/check-recovery-code
// POST /sign-in/check-pin

What we didn't pick: a single RPC-style endpoint (POST /flows/{flow} with {"step": "...", "payload": {...}}). It looks elegant, but you lose everything Laravel gives you per route: one FormRequest per step, per-route middleware and rate limits, route names, and OpenAPI generation. Our doc generator reads FlowRequest rules directly, so every step shows up documented with no extra work.

Also not picked: symfony/workflow or model-state packages. They're great, but they model the lifecycle of an entity that already exists (an order, an invoice). A sign-in flow has no entity yet. Before authenticate succeeds, we don't even know who the user is. Our flows are conversations, not record lifecycles.

2. The graph is a function, not a config file

nextSteps() and backSteps() take the current step and the full state:

abstract protected function nextSteps(string $current, FlowState $state): array;

This is how branching works. After authenticate, the next steps depend on $state->needMfa. We thought about a declarative graph in YAML or arrays, but every real flow needs conditions. Once a DSL grows conditions, you're writing a worse PHP. A match expression is readable, type-checked, and covered by your static analysis.

The order of the list matters: the first entry is the default the UI should show, and the rest are alternatives. ['check-mfa', 'check-recovery-code'] means "show the OTP screen, and offer an 'I lost my device' link".

3. Explicit back-edges and destructive rewind

Going back isn't a generic "undo". Each step says which earlier steps can be re-answered from it. Re-answering one rewinds the flow: onRewind() clears everything downstream.

The rewind is deliberately destructive. A partial merge would keep decisions made on outdated answers. Suppose a user changes their destination country after picking a payout method. That payout method may not exist in the new country, and silently keeping it is how bugs get into production.

One subtle point: the rewind only changes the in-memory state until the step commits.

if ($isBack) {
    // The rewind mutates the memo only: if the body later fails (e.g. a
    // throttle refusal), the cached flow must stay untouched, so the
    // write-through happens when the body commits via setState().
    $this->onRewind($stepName, $state);
}

If a re-answered step fails halfway (validation, rate limit, provider timeout), the user's flow in the cache is left exactly as it was.

4. The flow key is a ULID in the request body, not a session

initiateFlow() generates a ULID flow_key, stores the initial state, and returns it. Every later step sends it back.

What we didn't pick: server sessions or cookies. Our main client is a mobile app talking to a stateless API, users sometimes have two flows in progress at once, and we run on FrankenPHP workers. A flow key in the body is explicit, easy to test, and scoped to one flow. The ULID format is also validated cheaply (required|string|ulid) before we go to the cache.

5. State lives in the cache with a TTL, not the database

protected function setState(string $flowKey, FlowState $state): void
{
    $ttl = now()->addMinutes($this->staleTimeInMinutes ?? LaravelApiFlow::staleTime());

    $this->cache()->put("{$this->flowId}:{$flowKey}", $state->toArray(), $ttl);
    // ...
}

Flow state is ephemeral by design. An abandoned sign-in shouldn't leave a half-written row anywhere. The TTL also acts as a security boundary: an OTP challenge stored in a sign-in flow dies with the flow. Each write refreshes the TTL, so the timeout is "X minutes of inactivity", not "X minutes in total". When nextSteps() returns [], answer() calls forgetState() and the flow deletes itself.

The store is configurable (FLOW_CACHE_STORE). We used Redis as our storage.

6. Typed state

The state is a class, not an array:

class SignInState extends FlowState
{
    public ?string $customerId = null;
    public bool $needMfa = false;
    public ?MfaMode $mfaMode = null;
    public bool $verified = false;
    // constructor hydrates from the raw cached array, toArray() serialises back
}

Our first internal version used plain arrays described by a PHPStan array{...} shape. It worked, but typos in keys got through code review, and the "rules" of the flow ended up scattered across the arrays. More on that below.

7. Three layers of guards, each with its own status code

A step request goes through three checks, in this order:

Layer	Where	Fails with
Is the flow alive? Does it belong to you?	`FlowRequest::authorize()`	`410 FLOW_EXPIRED` / `403`
Is the payload valid?	`FlowRequest::rules()` (`ActiveFlowKey` + your `stepRules()`)	`422`
Is this step a legal transition right now?	`FlowController::validateStep()`	`409 FLOW_UNEXPECTED_STEP`

The order is intentional. If a flow has expired, the client should get a 410 and restart, not a 422 about a field on a screen it shouldn't be on. Each code maps to one client reaction: 410 -> restart the flow, 409 -> resync with the last next_steps, 422 -> show field errors. No more guessing from error messages.

A step request only declares its own fields:

use Na2axl\LaravelApiFlow\Http\FlowRequest;

class CheckMfaRequest extends FlowRequest
{
    protected bool $defaultAuthorize = true; // guest flow

    protected function stepRules(): array
    {
        return ['code' => ['required', 'string', 'regex:/^[0-9]{6}$/']];
    }
}

The flow id is resolved from the controller the route points to, so you don't have to repeat it.

8. Octane-safe memoization

This one is subtle. Laravel's Route objects keep their controller instance, so on long-lived runtimes (Octane, FrankenPHP workers) a controller can outlive a request. A naive $this->state cache on the controller would leak one user's flow into the next request.

State is memoized per request, and the memo resets when a new request arrives:

private function resetMemoOnNewRequest(): void
{
    $current = request();

    if ($this->memoRequest !== $current) {
        $this->stateMemo = [];
        $this->memoRequest = $current;
    }
}

How we handled authentication

Authentication shows up in two ways: flows that run before the user is authenticated (sign-in, register, forgot password), and flows that require an authenticated user (enable MFA, change password, set up a transaction PIN).

Guest flows: the flow key is a short-lived capability

For guest flows, the step requests set $defaultAuthorize = true. The only thing tying the steps together is the flow_key. That's acceptable because the key:

has 80 bits of randomness (ULID),
is scoped to one flow type ({flowId}:{flowKey} in the cache),
expires after a few minutes of inactivity,
only allows the transitions currently listed in next_steps.

So a stolen key from a sign-in flow that's sitting on check-mfa gives you the right to... guess a 6-digit OTP, on a rate-limited route, for a few minutes. It never gives you the right to skip to check-pin.

Authenticated flows: ownership is bound to the flow

For flows behind auth:sanctum, set $flowGuard on the controller:

class MfaEnableFlowController extends FlowController
{
    protected ?string $flowGuard = 'customer';
    // ...
}

Route::middleware('auth:sanctum')->group(function () {
    Route::flow('mfa-enable', MfaEnableFlowController::class);
});

Every time the flow commits state for an authenticated user, it also caches the owner's id next to it ({flowId}:{flowKey}:owner). FlowRequest::authorize() then compares that owner with the current user:

$user = $this->user($this->flowGuard);

if ($user) {
    return LaravelApiFlow::cache()->get("{$flowId}:{$flowKey}:owner") === $user->getAuthIdentifier();
}

return $this->defaultAuthorize;

Alice can't advance Bob's MFA setup even if she gets hold of his flow key: she gets a 403.

Sign-in itself: the token comes out of the last step

The main rule: a Sanctum token is only created in a terminal step. Here is a simplified version of our sign-in written against the package:

enum SignInStep: string
{
    case Initiate = 'initiate';
    case Authenticate = 'authenticate';
    case CheckMfa = 'check-mfa';
    case CheckRecoveryCode = 'check-recovery-code';
    case CheckPin = 'check-pin';
}

/** @extends FlowController<SignInState> */
final class SignInFlowController extends FlowController
{
    protected string $flowId = 'sign-in';
    protected string $flowStateClass = SignInState::class;
    protected ?string $flowGuard = 'customer';

    public function stepInitiate(): FlowResponse
    {
        return $this->initiateFlow();
    }

    public function stepAuthenticate(AuthenticateRequest $request): FlowResponse
    {
        $key = $request->flowKey();
        $this->validateStep($key, SignInStep::Authenticate);

        $customer = $this->customers->findByLogin($request->validated());

        if (! $customer || ! Hash::check($request->validated('password'), $customer->credential->password)) {
            // Nothing is committed: the flow stays on `authenticate`, the client can retry.
            throw new SignInFailed('wrong_password');
        }

        $needMfa = $customer->credential->tfa_enabled;

        if ($needMfa && $customer->credential->tfa_mode === MfaMode::PASSCODE) {
            $this->sendOtp->execute($request->validated('phone_number'), MessageChannel::SMS);
        }

        $this->appendState($key, [
            'customer_id' => $customer->id,
            'need_mfa' => $needMfa,
            'mfa_mode' => $customer->credential->tfa_mode,
            'verified' => ! $needMfa,
        ]);

        return $this->answer($key, SignInStep::Authenticate, ['need_mfa' => $needMfa]);
    }

    public function stepCheckPin(CheckPinRequest $request): FlowResponse
    {
        $key = $request->flowKey();
        $state = $this->validateStep($key, SignInStep::CheckPin);

        $customer = $this->customers->retrieve($state->customerId);
        $this->pins->check($customer, $request->validated('code')); // throws on failure

        // Terminal step: next_steps is empty, so answer() forgets the flow.
        return $this->answer($key, SignInStep::CheckPin, [
            'token' => $customer->createToken('mobile')->plainTextToken,
            'customer' => CustomerResource::make($customer),
        ]);
    }

    // stepCheckMfa / stepCheckRecoveryCode omitted for brevity

    protected function nextSteps(string $current, FlowState $state): array
    {
        return match (SignInStep::from($current)) {
            SignInStep::Initiate => [SignInStep::Authenticate->value],
            SignInStep::Authenticate => $state->needMfa
                ? [SignInStep::CheckMfa->value, SignInStep::CheckRecoveryCode->value]
                : [SignInStep::CheckPin->value],
            SignInStep::CheckMfa,
            SignInStep::CheckRecoveryCode => [SignInStep::CheckPin->value],
            SignInStep::CheckPin => [],
        };
    }

    protected function backSteps(string $current, FlowState $state): array
    {
        // "Use another account" from the 2FA screen
        return in_array($current, ['check-mfa', 'check-recovery-code'], true)
            ? [SignInStep::Authenticate->value]
            : [];
    }

    protected function onRewind(string $step, FlowState $state): void
    {
        if ($step === SignInStep::Authenticate->value) {
            $state->customerId = null;
            $state->needMfa = false;
            $state->verified = false;
        }
    }
}

A few things to notice:

The 2FA bypass can't happen. When needMfa is true, check-pin isn't in next_steps until check-mfa or check-recovery-code has committed. A client calling it early gets a 409, and nobody had to write an if.
A failed step doesn't commit. Wrong password, wrong OTP: we throw before answer(), so the machine stays where it was and the user can retry. Rate limiting is a normal route middleware.
The flow deletes itself at the end. Once the token is issued, the flow key is useless.
Cross-cutting context goes in the state too. In production, authenticate also records which data region the customer's records live in, so every later step talks to the right database without looking it up again.

The real flow has two more exits, which you can see in the diagram. A customer whose PIN was reset by support must choose a new one before getting a session. A customer who never set a transaction PIN gets handed off to the separate pin-code-setup flow. Flows can chain like this: one flow's terminal answer is another flow's entry ticket.

What we got out of it

One source of truth. The flow graph exists in exactly one place: a PHP match. You can read the whole business process in a single file.
The mobile app is a renderer. The mobile app maps a step name to a screen and shows next_steps[0]. Adding a branch, reordering steps or making a step conditional is a backend deploy, with no app store review, as long as the screen already exists. Old app versions follow the new graph automatically.
Secure by construction. Skipping, replaying or reordering steps is rejected by the engine, not by checks sprinkled around the code.
A consistent contract. Auth, KYC, transfers, PIN reset: every flow has the same envelope (data, next_steps, back_steps, flow_key) and the same error codes. The client handles 409 and 410 once, for all of them.
No dead rows. Abandoned flows expire from the cache. The database only ever sees finished business actions.
Tests that read like the spec. One feature test per edge: "from authenticate with 2FA, check-pin is a 409". The graph is also the test plan.
Routing and docs for free. One Route::flow() line per flow, and every step is a normal route with its own FormRequest that the OpenAPI generator already understands.

On the client side, the core loop looks roughly like this (simplified):

final res = await api.post('/sign-in/$step', {'flow_key': flowKey, ...payload});

switch (res.statusCode) {
  case 200:
    final next = List<String>.from(res.data['next_steps']);
    if (next.isEmpty) return onFlowCompleted(res.data['data']);
    router.go(screenFor(next.first), extra: FlowContext(
      flowKey: flowKey,
      alternatives: next.skip(1).toList(),
      back: List<String>.from(res.data['back_steps']),
    ));
  case 409: resyncWithLastKnownSteps();
  case 410: restartFlow();
  case 422: showFieldErrors(res.data['errors']);
}

The honest part: trade-offs

The cache is now critical infrastructure. If Redis is down, nobody can sign in. We accept that because the same is already true of sessions and rate limiting.
Flows are short-lived by design. A KYC review that waits two days for a compliance officer is not a flow. It's an entity with a lifecycle in the database. We use flows for the interactive part (collecting documents) and hand off to a persisted model at the end.
More round trips. One request per step instead of one big submit. On flaky mobile networks (pretty common in Africa), we found the extra round trips worth it, because each one returns immediate, specific feedback instead of a giant form failing at the end.
The client still has to know the screens. Server-driven navigation doesn't mean server-driven UI. The app needs a screen for every step name it might receive.

Wrapping up

The biggest change was a way of thinking, not code: stop mapping business processes one-to-one onto endpoints. An endpoint is how a transition reaches you. The process is the state machine, and it belongs on the server, in one place, enforced by default.

The first version lived in Zeney's shared package, and 22 flows across our services run on it today: sign-in, registration, password and PIN recovery, five KYC flows, wallet creation, payments, remittances, refunds, payment method setup, and more. Its guards were written by hand, as per-request checks on flags like verified === true. That was an implicit state machine: it worked, but the graph only existed in people's heads. Extracting it into a package was the chance to make the graph explicit, add proper back-navigation, and give every rejection its own status code.

The package supports PHP 8.2+ and Laravel 12/13, is MIT licensed, and is on GitHub:

na2axl / laravel-api-flow

Server-driven multi-step API flows for Laravel — declare steps as a state machine, let the API tell clients which steps are legal next.

Laravel API Flow

Server-driven multi-step API flows for Laravel. Declare your onboarding, checkout, or KYC flow as a state machine — the API tells clients which steps are legal next, so no frontend ever hardcodes the flow graph again.

The problem

Multi-step flows rot fast when step logic is scattered across controllers: the frontend hardcodes the step order, "go back" buttons break invariants, and skipped steps cause inconsistent state. This package moves the state machine to the server:

Each step declares which steps may follow it (nextSteps) and which earlier steps may be re-answered from it (backSteps)
Every response advertises the legal transitions (next_steps / back_steps) — the client just renders them
Illegal transitions are rejected with 409 FLOW_UNEXPECTED_STEP; expired flows with 410 FLOW_EXPIRED
Re-answering a step rewinds the flow: downstream state is discarded, never partially merged
One Route::flow() call registers the whole…

View on GitHub

composer require na2axl/laravel-api-flow

I'd love to hear how you model multi-step flows. Do you keep them on the server, the client, or somewhere in between? Issues, PRs and strong opinions are all welcome.

How to create a file watcher with PHP and the Elementary Framework

Nana Axel — Fri, 26 Jul 2019 16:16:32 +0000

Introduction

Welcome everyone to this second How-To about the Elementary Framework (for those who have missed the first How-To, check it here).

In this article we will talk about the creation of a file watcher, a console app which will watch files in a directory and report to us any changes made to these files (deletion, creation, modification), written in the PHP language using FireFS, a part of my framework.

Creating a file watcher it's just a possibility of FireFS between much more others.

Prerequisites

Before start, make sure you have:

A PHP IDE or editor: You can download Visual Studio Code, it's a free and powerful code editor which can support many languages (including PHP).
Composer: Composer is a dependencies manager for PHP projects. You can download it at https://getcomposer.org/

Part 1 - Preparing the project

The first thing we have to do is to create our new project. Create a new folder with the name you want, and open a terminal into it.

FireFS is a composer package, so we need first to prepare our project to use composer. In the terminal you previuously opened, type:

composer init

This will initialize our project with composer support. Follow the initialization process to the end.

Now, in the same terminal, we can install FireFS with the command:

composer require elementaryframework/fire-fs

And wait the process finish, this will download the source code of the FireFS project and install it in your own. When the installation succeed, type again:

composer dump-autoload -o

This will generate an optimized autoloader file (useful for production). For a normal autoload file, just omit the -o switch.

Once FireFS is installed, we can now create the command line tool to watch our files. Create a file named watch inside your project folder and insert into it:

#!/usr/bin/env php

<?php

// Require composer autoload file
require "./vendor/autoload.php";

// Print a message to the console
print "Hello world, this is a file watcher!";

What we are doing ?

We first require the autoloader file from composer
We print a message to the console output

To test if everything is working, just type in the terminal (while the working directory is the same as our project):

php watch

The console will print the text "Hello world, this is a file watcher!" before exit.

Note that the file name is watch (without any extension), and not watch.php

Part 2 - Our file watcher

Building a file watcher with FireFS is very easy, we just have to create a new FileSystemWatcher object, follow the build pattern and start it, easy, right?

The `FireFS` object

In FireFS, instances of the FireFS class represent a file system, and manage every files and folders in the given root directory. When creating a file watcher we have first to create a file system:

// We use the FireFS class
use ElementaryFramework\FireFS\FireFS;

// We create a new file system on the current directory
$fs = new FireFS();

This will create a file system at the same path than our watch file (to change the root path, just define your prefered path as the first parameter of the FireFS class constructor).

The watched folder

Now we have to create the folder which will be watched. We can let our console app do it itself by using the great FireFS API:

// Check if the directory to watch exists
if (!$fs->exists("files_to_watch")) {
    // If not, create the directory
    $fs->mkdir("files_to_watch");
}

This will create the directory files_to_watch only if it not exists at each run of our file watcher.

The `IFileSystemListener` object

Before enjoying our file watcher, we have to create a class implementing the IFileSystemListener interface. This class is used by the watcher to execute specific actions following the watch event (create, delete, update).

// We use the IFileSystemWatcher interface
use ElementaryFramework\FireFS\Listener\IFileSystemListener;

// We use the FileSystemEvent class
use ElementaryFramework\FireFS\Events\FileSystemEvent;

// Our listener
class WatcherListener implements IFileSystemListener
{
    /**
     * Action executed on any event.
     * The returned boolean will define if the
     * specific event handler (onCreated, onModified, onDeleted)
     * have to be called after this call.
     */
    public function onAny(FileSystemEvent $event): bool
    {
        $eventType = $event->getEventType();
        $date = date("d/m/Y H:i:s");

        if ($eventType === FileSystemEvent::EVENT_UNKNOWN) {
            return true;
        }

        switch ($eventType) {
            case FileSystemEvent::EVENT_CREATE:
                print "{$date}  -  [Created]  {$event->getPath()}\n";
                break;

            case FileSystemEvent::EVENT_MODIFY:
                print "{$date}  -  [Updated]  {$event->getPath()}\n";
                break;

            case FileSystemEvent::EVENT_DELETE:
                print "{$date}  -  [Deleted]  {$event->getPath()}\n";
                break;
        }

        return false;
    }

    /**
     * Action executed when a file/folder is created.
     */
    public function onCreated(FileSystemEvent $event)
    { }

    /**
     * Action executed when a file/folder is updated.
     */
    public function onModified(FileSystemEvent $event)
    { }

    /**
     * Action executed when a file/folder is deleted.
     */
    public function onDeleted(FileSystemEvent $event)
    { }
}

The `FileSystemWatcher` object

Once we have a file system object and we know the directory (or the file) we want to watch, we can create the file watcher:

// We use the FileSystemWatcher class
use ElementaryFramework\FireFS\Watcher\FileSystemWatcher;

// Create the file watcher
$watcher = new FileSystemWatcher($fs);

The next step is to configure our watcher. The configuration is done by calling some methods:

setListener(IFileSystemListener): Defines the IFileSystemListener instance used to execute specific actions on each files updates ;
setPath(string): Defines the path of directory/file to watch ;
setRecursive(bool): Defines if the watcher will watch for files recursively (works only if the watched entity is a directory) ;
addPattern(Regex): Add a files-to-watch pattern ;
addExcludePattern(Regex): Add a files-to-exclude pattern ;
setPattern(array): Set an array of files-to-watch patterns. This will overwrite any existing pattern ;
setExcludePattern(array): Set an array of files-to-exclude patterns. This will overwrite any existing pattern ;
setWatchInterval(int): Set the interval in milliseconds in which the watcher will process a watch event.

So we will build our watcher like this:

$watcher
    ->setListener(new WatcherListener)
    ->setRecursive(true)
    ->setPath("./files_to_watch")
    ->setWatchInterval(250)
    ->build(); // It's important to call build to validate the configuration

Important to know: The FileSystemWatcher class have some default exclude patterns, check them here

At this time, everything is set! Now the last thing to do is to start the watcher:

// Start the file watcher
$watcher->start();

The complete `watch` file

We just have finished to create our file watcher, there is the complete file content:

#!/usr/bin/env php

<?php

// Require composer autoloader
require_once __DIR__ . '/vendor/autoload.php';

// We use the FireFS class
use ElementaryFramework\FireFS\FireFS;

// We use the IFileSystemWatcher interface
use ElementaryFramework\FireFS\Listener\IFileSystemListener;

// We use the FileSystemEvent class
use ElementaryFramework\FireFS\Events\FileSystemEvent;

// We use the FileSystemWatcher class
use ElementaryFramework\FireFS\Watcher\FileSystemWatcher;

// We create a new file system on the current directory
$fs = new FireFS();

// Check if the directory to watch exists
if (!$fs->exists("files_to_watch")) {
    // If not, create the directory
    $fs->mkdir("files_to_watch");
}

// Our listener
class WatcherListener implements IFileSystemListener
{
    /**
     * Action executed on any event.
     * The returned boolean will define if the
     * specific event handler (onCreated, onModified, onDeleted)
     * have to be called after this call.
     */
    public function onAny(FileSystemEvent $event): bool
    {
        $eventType = $event->getEventType();
        $date = date("d/m/Y H:i:s");

        if ($eventType === FileSystemEvent::EVENT_UNKNOWN) {
            return true;
        }

        switch ($eventType) {
            case FileSystemEvent::EVENT_CREATE:
                print "{$date}  -  [Created]  {$event->getPath()}\n";
                break;

            case FileSystemEvent::EVENT_MODIFY:
                print "{$date}  -  [Updated]  {$event->getPath()}\n";
                break;

            case FileSystemEvent::EVENT_DELETE:
                print "{$date}  -  [Deleted]  {$event->getPath()}\n";
                break;
        }

        return false;
    }

    /**
     * Action executed when a file/folder is created.
     */
    public function onCreated(FileSystemEvent $event)
    { }

    /**
     * Action executed when a file/folder is updated.
     */
    public function onModified(FileSystemEvent $event)
    { }

    /**
     * Action executed when a file/folder is deleted.
     */
    public function onDeleted(FileSystemEvent $event)
    { }
}

// Create the file watcher
$watcher = new FileSystemWatcher($fs);

$watcher
    ->setListener(new WatcherListener)
    ->setPath("./files_to_watch")
    ->setWatchInterval(250)
    ->build(); // It's important to call build to validate the configuration

// Start the file watcher
$watcher->start();

Now run this file using the command php watch, a new folder files_to_watch is directly created and the console wait for files changes. Try to create, delete or edit files inside the files_to_watch folder and you will be directly notified for these actions inside the console!

php watch

26/07/2019 15:53:20  -  [Created]  D:\AliensGroup\Hyde\hyde-cli\files_to_watch\composer.json
26/07/2019 15:54:24  -  [Created]  D:\AliensGroup\Hyde\hyde-cli\files_to_watch\composer.lock
26/07/2019 15:54:24  -  [Created]  D:\AliensGroup\Hyde\hyde-cli\files_to_watch\hyde
26/07/2019 15:54:29  -  [Deleted]  D:\AliensGroup\Hyde\hyde-cli\files_to_watch\composer.lock
26/07/2019 15:54:47  -  [Updated]  D:\AliensGroup\Hyde\hyde-cli\files_to_watch\hyde

Conclusion

With this article, we have learn How to create a file watcher with PHP and the Elementary Framework. Using the FireFS module of the framework, we have seen steps by steps how it's very easy to implement a functionality like this. Now with the knowledge you have you can create more than a simple event reporting app, from crons on your webserver, to your own Jekyll PHP edition ;-), you have everything you need to go further.

What next?

Browse the FireFS source code on GitHub - and give a star if you like it - ;
Checkout other Elementary Framework modules

ElementaryFramework / FireFS

Easily manage your filesystem through PHP

FireFS

Manage your file system easily, through php

FireFS is a library allowing you to write/read/delete files and folders of your file system, safely and easily.

It can be used for web applications as well for console applications, without any requirements.

Example

<?php
use ElementaryFramework\FireFS\FireFS;

// Create a new file system instance at the given path
$fs = new FireFS("./app"); // /root/var/www/htdocs/app/

// Check if the path "/root/var/www/htdocs/app/images/" exists
if ($fs->exists("images")) {
    // Change the working directory to the images folder
    $fs->setWorkingDirectory("./images");

    // Create a new file in the working directory
    $fs->mkfile("./logo.png"); // /root/var/www/htdocs/app/images/logo.png

    // Read file from the file system root path
    $logo = $fs->read("logo.png"

…

View on GitHub

How to create a RESTful API with PHP and the Elementary Framework

Nana Axel — Fri, 11 Jan 2019 02:14:53 +0000

Introduction

With new web technologies, when we want to build a web site we think about front-end frameworks like React.js, AngularJS, Vue.js and so on... But what happen for the dark side of the website, the back-end?

For a simple website, like a one page portfolio or a landing page, the development of the back-end is not very necessary. But when we want to interact with a database or upload files, this become mandatory.

The problem is when we use front-end web technologies like React.js, we cannot directly interact with any back-end server language (PHP, Python, Ruby, and even Javascript with Node.js, etc...). This is where the RESTful API model takes place.

With a back-end server implementing the REST software architecture, the only thing you have to do from the front-end is to make an AJAX request for an URI to your server, passing to it some values as request parameters, and waiting for the server response.

This is what we will learn with this How-To. We will create a RESTful API server, using the PHP language, and a framework I have built, the Elementary Framework.

Prerequisites

Before start, make sure you have:

A PHP IDE or editor: Guys at Microsoft have made an awesome work on Visual Studio Code, a free and powerful code editor.
Composer: Composer is a dependencies manager for PHP projects. You can download it at https://getcomposer.org/
A RESTful API development environment: Since we will not create a front-end app in this How-To, we will use instead a RESTful API development environment. You can check the Postman project, it's a complete API development environment software, and the one I we will use for our project.

Part 1 - Preparing the project

We will start by creating our new project. Create a new folder, with the name you want (in this tutorial, the project name will be php_rest_api) and open a terminal into it.

Since Elementary Framework modules are composer packages, we will install the module responsible of our API (WaterPipe) with composer. In the terminal you have previously opened, type:

composer init

This will initialize an empty composer project. Just follow the initialization process to the end. When the process finish, you can now install WaterPipe with:

composer require elementaryframework/water-pipe

And wait the process finish, this will download the source code of the project and install it in your own. When the installation succeed, type again:

composer dump-autoload -o

This will generate an optimized autoloader file (useful for production). For a normal autoload file, just omit the -o switch.

Now we have installed WaterPipe, the next step is to create the entry point of our API. For our project, it will be a simple index.php file. So, create a file named index.php and insert into it:

<?php

// Require composer autoload file
require "./vendor/autoload.php";

// Require the main WaterPipe class
use ElementaryFramework\WaterPipe\WaterPipe;

// Create the base pipe
$basePipe = new WaterPipe;

// Run the pipe and serve the API
$basePipe->run();

What we are doing ?

We first require the autoloader file from composer
We can now require the main class of WaterPipe, using the namespace (this is the magic of the autoloader)
We create a new instance of WaterPipe into $basePipe
We run the pipe with $basePipe->run()

This is the minimal content of our project. If you upload this to your server and open the web page into your browser, you will surely get an error, don't worry, this is because we are running an empty pipe, we have to add some water to it ;-)

Part 2 - Thinking our API

Before write an API, we have to know exactly what we want to do, and how it will be done. You have to make this work alone for your project, since you exactly know your needs.

What we want to do?

Here we have to find API requests we have to write, from analyzing the front-end requirements (user registration, files uploading, database access, etc...).

For example, in this project we will:

Create an URI used to login the user
Create an URI used to retrieve a list blog posts
Create an URI used to retrieve a single blog post
Create an URI used to access an asset file stored into the server
Disallow access to all other requests

How it will be done?

Here we have to find how requests will be executed. Just take a paper and imagine a request sent to your server and how the server handle it, what kind of data have to be sent from the browser, what will be sent back from the server, what resource will be used, etc... This is an important process not only in this case but in the software development generally.

For example, in this project, the /api/login URI have to receive, with the POST method, the username and the password of the user who want to login, if informations are correct, we can create a session with these informations, and then, return a successful signal to the client. If informations are incorrect, return an unsuccessful signal to the client, followed by an error message.

Repeat these steps until you have reviewed all you have to do in your API. If so, you can go ahead and continue to the next part.

Part 3 - Writing our API

Receiving requests

The API of WaterPipe is designed to be easily understandable. When you are writing your API with it, there are some methods you have to know:

get(string $uri, callable $action) : Which run the specified $action when receiving a GET request at the given $uri
post(string $uri, callable $action) : Which run the specified $action when receiving a POST request at the given $uri
put(string $uri, callable $action) : Which run the specified $action when receiving a PUT request at the given $uri
delete(string $uri, callable $action) : Which run the specified $action when receiving a DELETE request at the given $uri
patch(string $uri, callable $action) : Which run the specified $action when receiving a PATCH request at the given $uri
head(string $uri, callable $action) : Which run the specified $action when receiving a HEAD request at the given $uri
request(string $uri, callable $action) : Which run the specified $action when receiving any kind of request at the given $uri

So going to more practice! Open our index.php file in your code editor/IDE, we are going to write our first request:

<?php

// Require composer autoload file
require "./vendor/autoload.php";

// Require the main WaterPipe class
use ElementaryFramework\WaterPipe\WaterPipe;

// Require the Request class
use ElementaryFramework\WaterPipe\HTTP\Request\Request;
// Require the Response class
use ElementaryFramework\WaterPipe\HTTP\Response\Response;

// Create the base pipe
$basePipe = new WaterPipe;

// Handle any kind of requests made at the root of the pipe
$basePipe->request("/", function (Request $req, Response $res) {
    $res->sendText("Welcome to my API");
});

// Run the pipe and serve the API
$basePipe->run();

What we are doing ?

We require the Request class
We require the Response class
We write a request handler for the / URI (the root URI)
We send the text Welcome to my API as the response

Upload this to your server and open your browser, you certainly see the text Welcome to my API shown into your browser, you have wrote your first request ! Nothing awesome, I know...

I think you have now some ideas on how to write request handlers with WaterPipe. This request was just used for a demonstration, you can now delete it and just leave use statements.

Handling a POST request

Now we can go ahead and write our first request defined in the part 2, the login URI:

<?php

// Start a session
session_start();

// Require composer autoload file
require "./vendor/autoload.php";

// Require the main WaterPipe class
use ElementaryFramework\WaterPipe\WaterPipe;

// Require the Request class
use ElementaryFramework\WaterPipe\HTTP\Request\Request;
// Require the Response class
use ElementaryFramework\WaterPipe\HTTP\Response\Response;

// Create the base pipe
$basePipe = new WaterPipe;

// Our login request
$basePipe->post("/api/login", function (Request $req, Response $res) {
    // Get request data sent by the client
    $body = $req->getBody();
    $username = $body["username"];
    $password = $body["password"];

    // Check data
    // Since this How-To will not handle connections to database,
    // We will made a simple comparison here...
    if ($username === $password) {
        // Create the user session
        $_SESSION["username"] = $username;
        // Send a successful signal to the client
        $res->sendJson(array(
            "success" => true
        ));
    } else {
        // Send an unsuccessful signal to the client
        $res->sendJson(array(
            "success" => false,
            "error" => "Username and password mismatch"
        ));
    }
});

// Run the pipe and serve the API
$basePipe->run();

What we are doing ?

We start a session with session_start()
We create our login request with the POST method
We retrieve request body through $req->getBody()
We compare retrieved data for equality (you have to use your own login algorithm here)
- On comparison success
  - We create the user session
  - We send the successful signal to the client (as a JSON response)
- On comparison fails
  - We send the unsuccessful signal with the error message to the client (as a JSON response)

Now we are going to test our API. Start you API development environment software, and configure it to test the API we have just wrote. Send some data and see what is returned, when the username and the password sent to the server are equals, you will certainly get a successful signal:

And when these informations mismatch, you got an unsuccessful signal:

Handling a GET request

Now we are about to write one of our blog posts requests. We will write the request responsible to return the list of published posts. I think you certainly have some ideas on what we have to do ;-)

For next examples, to do not repeat code, consider that we are writting code snippets just before the $basePipe->run() instruction:

// Our posts retrieving request
$basePipe->get("/api/posts/get", function (Request $req, Response $res) {
    // Retrieve posts from the database, or any other data storage...
    // Since this How-To will not handle connections to database,
    // We will just return static data here...
    $res->sendJSON(array(
      "success" => true,
      "posts" => array(
        array(
          "title" => "First blog post",
          "description" => "The first public post of this blog",
          "author" => "Nana Axel"
        ),
        array(
          "title" => "Second blog post",
          "description" => "The second public post of this blog",
          "author" => "Nana Axel"
        ),
        array(
          "title" => "Another blog post",
          "description" => "Just another public post of this blog",
          "author" => "Nana Axel"
        )
      )
    ));
});

Simple I know, but the logic is here, you just have to retrieve the list of blog posts somewhere, send the list as a JSON object to the client, and parse it with your front-end framework to display it into your web page.

Now we will made something more excitant, we will retrieve data for a single post:

// Our single post retrieving request
$basePipe->get("/api/posts/get/:id", function (Request $req, Response $res) {
    // Get the id parameter from the URI
    $params = $req->uri->getParams();
    $postId = intval($params["id"]);

    // Retrieve post from the database, or any other data storage...
    // Since this How-To will not handle connections to database,
    // We will just return static data here...
    $post = array();
    $success = true;

    switch ($postId) {
      case 1:
        $post = array(
          "title" => "First blog post",
          "description" => "The first public post of this blog",
          "content" => "This first post is not very excitant, just a way for me to say Hello, World !",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:01",
          "category" => null
        );
        break;

      case 2:
        $post = array(
          "title" => "Second blog post",
          "description" => "The second public post of this blog",
          "content" => "I love C#, Microsoft guys have built an awesome language! Now I'm developing a game engine with it. It will support all platforms and allow user to also make game scripts with Lua and Javascript :-D",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:05",
          "category" => "Dev"
        );
        break;

      case 3:
        $post = array(
          "title" => "Another blog post",
          "description" => "Another public post of this blog",
          "content" => "React.js or AngularJS? Who is the best? Just leave your opinion as comment ;-)",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:07",
          "category" => "Poll"
        );
        break;

      default:
        $success = false;
        break;
    }

    // Send the retrieved post
    $res->sendJSON(array(
      "success" => $success,
      "post" => $post
    ));
});

Have you seen how we have got the id of the post to retrieve? Now, using your API development environment software, try to access to /api/posts/get/1 for example and see the result, it is the first post which is returned!

This is the way WaterPipe uses to get values from the request URI. You are able to use an infinite number of parameters, WaterPipe will just check if a request URI matches with the given one, and will automatically parse this URI to retrieve parameters value.

Now going to a more complex request, we want to send an image to the client. Reading this, some people will say:

Why a request like that? We can just use the URL to the file!

Some times, it is not possible... Due to the project architecture, or when it is necessary to do not let the user know how files are structured in your server.

// Our image retrieving request
$basePipe->get("/assets/images/(.+)", function (Request $req, Response $res) {
    // Retrieve the path to the image from the request
    $params = $req->uri->getParams();
    $path = $params[0];

    // Just send the image file from our secret folder
    $res->sendFile("/path/to/our/secret/assets/folder/images/{$path}");
});

Hell yeah! WaterPipe have a full support of regex-based requests! The only difference with the previous example is when using named parameters in requests, the parameter value is accessed from the request URI with his name ($params["id"]). And when using regex-based parameters in request, the parameter value is accessed from the request URI with his position in the URI ($params[0]).

Hacking requests

It is possible to combine named and regex-based parameters. Even in this case, the previous rule apply.

$basePipe->get("/assets/:type/(.+)", function (Request $req, Response $res) {
    // Retrieving parameters from the request
    $params = $req->uri->getParams();
    $type = $params["type"];
    $path = $params[1]; // Position 1 because the parameter :type occupy the position 0

    // Just send the file from our secret folder
    $res->sendFile("/path/to/our/secret/assets/folder/{$type}/{$path}");
});

To handle request like /path/of/request?param1=value1&param2=value2, you don't have to explicitly specify GET parameters, and you dont have to use regex. Just create a request handler with the /path/of/request URI, and retrieve GET parameters into it:

$basePipe->get("/path/of/request", function (Request $req, Response $res) {
    // Retrieving GET parameters from the request
    $params = $req->getParams();
    $param1 = $params["param1"];
    $param2 = $params["param2"];

    $res->sendText("param1={$param1}&param2={$param2}");
});

GET parameters are retrieved with the getParams() method of the Request class. This is totally different from the getParams() method of the RequestUri class which returns URI parameters.

Sending responses

With the previous set of examples, we have used some shortcut methods to directly send a response in a predefined format. All shortcut methods are:

sendHTML(string $html, int $status = 200): Used to send an HTML response.
sendJSONString(string $json, int $status = 200): Used to send a JSON response.
sendJSON(array $json, int $status = 200): Used to send a JSON response.
sendText(string $text, int $status = 200): Used to send a plain text response.
sendFile(string $path, int $status = 200, string $mime = null): Used to send a file content as a response, can be an image, a css/js file, an HTML file, etc...

When you want to have the full power on the server response, you have to configure the response yourself.

To let you see how you can achieve this, we will send the successful signal to the client with raw methods.

The first step is to define the header of the response:

// Create a new response header
$header = new ResponseHeader();

// Define the response header
$res->setHeader($header);

Since we want to send a JSON response, we have to define the Content-Type header value to application/json. If you don't know what we are talking about, I suggest you to read about HTTP headers and MIME types.

// Create a new response header
$header = new ResponseHeader();
// Define header values
$header->setContentType("application/json");

// Define the response header
$res->setHeader($header);

The second step is to define the response status.

// Create a new response header
$header = new ResponseHeader();
// Define header values
$header->setContentType("application/json");

// Create a new response status
$status = new ResponseStatus(ResponseStatus::OkCode);

$res
  ->setHeader($header) // Define the response header
  ->setStatus($status) // Define the response status
  ;

The last step is to define the response body.

// Create a new response header
$header = new ResponseHeader();
// Define header values
$header->setContentType("application/json");

// Create a new response status
$status = new ResponseStatus(ResponseStatus::OkCode);

// Build the response body
$body = json_encode(array(
  "success" => true
));

$res
  ->setHeader($header) // Define the response header
  ->setStatus($status) // Define the response status
  ->setBody($body) // Define the response body as string
  ;

When you have finished to setup your response, just send it to the client.

// Create a new response header
$header = new ResponseHeader();
// Define header values
$header->setContentType("application/json");

// Create a new response status
$status = new ResponseStatus(ResponseStatus::OkCode);

// Build the response body
$body = json_encode(array(
  "success" => true
));

$res
  ->setHeader($header) // Define the response header
  ->setStatus($status) // Define the response status
  ->setBody($body) // Define the response body as string
  ->send() // Send the response to the client and close
  ;

Manually send response parts

With WaterPipe, you are able to send manually response parts (headers and body) by using methods :

sendHeaders() to send headers defined by setHeaders(ResponseHeader) ;
sendBody() to send the response body defined by setBody(string) ;
close() to ensure that your response is closed after everything is sent.

// Define your headers using $res->setHeaders($headers) according to the request...

// Send the response headers first
$res->sendHeaders();

// Compute the response body (read database, file, custom content, etc...)

// Define the response body using $res->setBody($body)

// Send the response body
$res->sendBody();

// You can redefine the body and send it mutiple times in the same response!

// Doing some shutdown process...

// Close the response
$res->close();

// Everything after a $res->close() call will not be executed!

Handling common HTTP errors

It's common that an user fall into a 404 error, or your server have some troubles and return a 500 error. WaterPipe allow you to easily handle these errors, for example we will disallow access to all other requests to our server.

$basePipe->error(ResponseStatus::NotFoundCode, function (Request $req, Response $res) {
    // Just send a forbidden response
    $res->sendText("Forbidden.", ResponseStatus::ForbiddenCode);
});

What we are doing ?

We create a request handler for the 404 HTTP error
We send back to the client a 403 HTTP error (Forbidden error)

In other words we are transforming all possible 404 errors from our API to a 403 error.

Now you know all the basics to build your API with WaterPipe. If you are interested, just continue to play with it, or browse the source code to learn more.

Part 3 - Some advanced tips

Using sub-pipes

For now, our index.php file look at this:

<?php

// Start a session
session_start();

// Require composer autoload file
require "./vendor/autoload.php";

// Require the main WaterPipe class
use ElementaryFramework\WaterPipe\WaterPipe;

// Require the Request class
use ElementaryFramework\WaterPipe\HTTP\Request\Request;
// Require the Response class
use ElementaryFramework\WaterPipe\HTTP\Response\Response;
// Require the ResponseStatus class
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseStatus;

// Create the base pipe
$basePipe = new WaterPipe;

// Our login request
$basePipe->post("/api/login", function (Request $req, Response $res) {
    // Get request data sent by the client
    $body = $req->getBody();
    $username = $body["username"];
    $password = $body["password"];

    // Check data
    // Since this How-To will not handle connections to database,
    // We will made a simple comparison here...
    if ($username === $password) {
        // Create the user session
        $_SESSION["username"] = $username;
        // Send a successful signal to the client
        $res->sendJson(array(
            "success" => true
        ));
    } else {
        // Send an unsuccessful signal to the client
        $res->sendJson(array(
            "success" => false,
            "error" => "Username and password mismatch"
        ));
    }
});

// Our posts retrieving request
$basePipe->get("/api/posts/get", function (Request $req, Response $res) {
    // Retrieve posts from the database, or any other data storage...
    // Since this How-To will not handle connections to database,
    // We will just return static data here...
    $res->sendJSON(array(
      "success" => true,
      "posts" => array(
        array(
          "title" => "First blog post",
          "description" => "The first public post of this blog",
          "author" => "Nana Axel"
        ),
        array(
          "title" => "Second blog post",
          "description" => "The second public post of this blog",
          "author" => "Nana Axel"
        ),
        array(
          "title" => "Another blog post",
          "description" => "Just another public post of this blog",
          "author" => "Nana Axel"
        )
      )
    ));
});

// Our single post retrieving request
$basePipe->get("/api/posts/get/:id", function (Request $req, Response $res) {
    // Get the id parameter from the URI
    $params = $req->uri->getParams();
    $postId = intval($params["id"]);

    // Retrieve post from the database, or any other data storage...
    // Since this How-To will not handle connections to database,
    // We will just return static data here...
    $post = array();
    $success = true;

    switch ($postId) {
      case 1:
        $post = array(
          "title" => "First blog post",
          "description" => "The first public post of this blog",
          "content" => "This first post is not very excitant, just a way for me to say Hello, World !",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:01",
          "category" => null
        );
        break;

      case 2:
        $post = array(
          "title" => "Second blog post",
          "description" => "The second public post of this blog",
          "content" => "I love C#, Microsoft guys have built an awesome language! Now I'm developing a game engine with it. It will support all platforms and allow user to also make game scripts with Lua and Javascript :-D",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:05",
          "category" => "Dev"
        );
        break;

      case 3:
        $post = array(
          "title" => "Another blog post",
          "description" => "Another public post of this blog",
          "content" => "React.js or AngularJS? Who is the best? Just leave your opinion as comment ;-)",
          "author" => "Nana Axel",
          "published_date" => "01/10/2019 06:07",
          "category" => "Poll"
        );
        break;

      default:
        $success = false;
        break;
    }

    // Send the retrieved post
    $res->sendJSON(array(
      "success" => $success,
      "post" => $post
    ));
});

$basePipe->get("/assets/:type/(.+)", function (Request $req, Response $res) {
    // Retrieving parameters from the request
    $params = $req->uri->getParams();
    $type = $params["type"];
    $path = $params[1]; // Position 1 because the parameter :type occupy the position 0

    // Just send the file from our secret folder
    $res->sendFile("/path/to/our/secret/assets/folder/{$type}/{$path}");
});

$basePipe->error(ResponseStatus::NotFoundCode, function (Request $req, Response $res) {
    // Just send a forbidden response
    $res->sendText("Forbidden.", ResponseStatus::ForbiddenCode);
});

// Run the pipe and serve the API
$basePipe->run();

Imagine that in the next ages of our project we want to change our URI, replacing /api/** to /backend/**. With our current file, we have to replace /api/** at each requests, I know it will be not too difficult, but imagine if you have much more requests.

It's for these cases (and much more others) that sub-pipe becomes important. It allow you to run an entire pipe within a single base URI. Now let us edit our file to implement a sub-pipe for our api:

<?php

// Start a session
session_start();

// Require composer autoload file
require "./vendor/autoload.php";

// Require the main WaterPipe class
use ElementaryFramework\WaterPipe\WaterPipe;

// Require the Request class
use ElementaryFramework\WaterPipe\HTTP\Request\Request;
// Require the Response class
use ElementaryFramework\WaterPipe\HTTP\Response\Response;
// Require the ResponseStatus class
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseStatus;

// Create the base pipe
$basePipe = new WaterPipe;

// Create the sub-pipe for requests starting with /api/
$apiPipe = new WaterPipe;

// Our login request
$apiPipe->post("/login", function (Request $req, Response $res) {
  // Request execution...
});

// Our posts retrieving request
$apiPipe->get("/posts/get", function (Request $req, Response $res) {
  // Request execution...
});

// Our single post retrieving request
$apiPipe->get("/posts/get/:id", function (Request $req, Response $res) {
  // Request execution...
});

// Add the API sub-pipe to the base pipe
$basePipe->pipe("/api", $apiPipe);

$basePipe->get("/assets/:type/(.+)", function (Request $req, Response $res) {
  // Request execution...
});

$basePipe->error(ResponseStatus::NotFoundCode, function (Request $req, Response $res) {
  // Request execution...
});

// Run the pipe and serve the API
$basePipe->run();

To append a sub-pipe to the root pipe, we use the pipe(string $baseUri, WaterPipe $pipe) method from the WaterPipe class. This method will tell to the root pipe to run the given sub-pipe requests when and only when the client request starts with the given base URI.

This is helpful when your file is growing, and you want to separate your api within files, like api.users.php, api.posts.php, api.assets.php, etc... and merge all these files into index.php.

Sub-pipes can also contains other sub-pipes, and so on...

Using middlewares

Now we want to allow access to our API only for connected users, and when a connected user send a request, we want to add into the response a custom HTTP header, which will hold the username. Instead of editing all request handlers to check if the user is connected and hack the response header, we can create a Middleware, to execute a specific action before the request is executed, and another before the response is sent.

class ApiMiddleware extends Middleware
{
    public function beforeExecute(Request &$request)
    {
        // If the session doesn't exists and we are not executing the login request
        if (!isset($_SESSION["username"]) && !$request->uri->is("/api/login")) {
            // Just send a forbidden response
            (new Response)->sendText("Forbidden", ResponseStatus::ForbiddenCode);
        }
    }

    public function beforeSend(Response &$response)
    {
        // If the session exists
        if (isset($_SESSION["username"])) {
            $header = $response->getHeader();
            $header->setField("X-Username", $_SESSION["username"]);
            $response->setHeader($header);
            // DO NOT send the response here, except if you have to change the response to be sent (send an error instead for example)
        }
    }
}

And then use it into our base pipe.

$basePipe->use(new ApiMiddleware);

Part 4 - Deploy it!

Since when used, WaterPipe handle all your incoming requests, it's important to configure your HTTP server to redirect all (or some of) these requests to the root pipe of your project (in this case, index.php).

Apache

For Apache, you have to edit the .htaccess file located in the root of your app, and add these lines:

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

This will send all requests to the index.php file (you can replace it with any other file which contains your root pipe).

NGiNX

Configure NGiNX is pretty easy, you just have to add (or update) the location / command of your server block. It have to look like:

location / {
    try_files $uri $uri/ /index.php?$args;
}

This will say to NGiNX to redirect all non existing paths to the index.php file (you can replace it with any other file which contains your root pipe).

If you want to redirect all paths without distinction, you have to do:

location / {
    try_files /index.php?$args;
}

Conclusion

With this article, we have learn How to build a RESTful API server using PHP and the Elementary Framework. We have seen steps by steps, the basics and some advanced tips, on how to use WaterPipe, the part of the Elementary Framework responsible of handling requests and sending responses. With what we have done, you surely know how to use this package to create more than a RESTful API, but also URL routing frameworks for your projects and more!

Thank you for reading this article to the end. I'm open to any questions, suggestions, and - constructive - critics about this article, and my framework, just post a comment! Sorry if you search for an API documentation of this framework, there is no one for now, but I'm actively working on this. Also, any contribution is kindly appreciated, just open an issue, or more, a pull request!

What next?

Browse the WaterPipe source code on GitHub - and give a star if you like it - ;
Checkout other Elementary Framework modules

ElementaryFramework / WaterPipe

URL routing framework, requests/responses handler, and HTTP client for PHP

WaterPipe

A powerful routing framework and requests/responses handler for PHP

WaterPipe is a library which allows you to easily handle HTTP requests and responses with PHP, giving you all the power to build a fully RESTful API, to create a routing framework for your web application, etc...

Example

<?php
use ElementaryFramework\WaterPipe\WaterPipe;

use ElementaryFramework\WaterPipe\HTTP\Request\Request;

use ElementaryFramework\WaterPipe\HTTP\Response\Response;
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseStatus;
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseHeader;

// Create the root pipe
$root = new WaterPipe;

// Add a new route to the pipe with HTTP GET method (the home page)
$root->get("/", function (Request $req, Response $res) {
    $res->sendHtml

…

View on GitHub

DEV Community: Nana Axel

Fan-out on read vs fan-out on write: choosing the right trade-off for a dynamic feed

First, what is being fanned out?

Fan-out on write: prepare the feed ahead of time

Fan-out on read: assemble the feed when it is requested

The trade-off

Why many systems use a hybrid

Ask questions before choosing

If your mobile app decides which step comes next, your backend is trusting the client, and this won't scale. This is why at Zeney Pay, we moved to a backend-authored state machine. Let's explore the design decisions and the trade-offs we accepted.

I built a generic multi-step flow engine on top of Laravel controllers

I built a generic multi-step flow engine on top of Laravel controllers

How it went wrong

Starting with sign-in

The package in 60 seconds

The design decisions (and what we didn't pick)

1. The flow is a controller, and each step is a real route

2. The graph is a function, not a config file

3. Explicit back-edges and destructive rewind

4. The flow key is a ULID in the request body, not a session

5. State lives in the cache with a TTL, not the database

6. Typed state

7. Three layers of guards, each with its own status code

8. Octane-safe memoization

How we handled authentication

Guest flows: the flow key is a short-lived capability

Authenticated flows: ownership is bound to the flow

Sign-in itself: the token comes out of the last step

What we got out of it

The honest part: trade-offs

Wrapping up

na2axl / laravel-api-flow

Server-driven multi-step API flows for Laravel — declare steps as a state machine, let the API tell clients which steps are legal next.

Laravel API Flow

The problem

How to create a file watcher with PHP and the Elementary Framework

Introduction

Prerequisites

Part 1 - Preparing the project

Part 2 - Our file watcher

The FireFS object

The watched folder

The IFileSystemListener object

The FileSystemWatcher object

The complete watch file

Conclusion

What next?

ElementaryFramework / FireFS

Easily manage your filesystem through PHP

FireFS

Example

How to create a RESTful API with PHP and the Elementary Framework

Introduction

Prerequisites

Part 1 - Preparing the project

Part 2 - Thinking our API

What we want to do?

How it will be done?

Part 3 - Writing our API

Receiving requests

Handling a POST request

Handling a GET request

Hacking requests

Sending responses

Manually send response parts

Handling common HTTP errors

Part 3 - Some advanced tips

Using sub-pipes

Using middlewares

Part 4 - Deploy it!

Apache

NGiNX

Conclusion

What next?

ElementaryFramework / WaterPipe

URL routing framework, requests/responses handler, and HTTP client for PHP

WaterPipe

Example

The `FireFS` object

The `IFileSystemListener` object

The `FileSystemWatcher` object

The complete `watch` file