DEV Community: Taras Hanych

A timeout tells you what you know. Not what the receiver did.

Taras Hanych — Thu, 08 Oct 2026 12:30:00 +0000

Picture an integration. Your app sends a webhook: order 42 is confirmed, please create the shipment. The partner commits the shipment and returns success. The connection breaks before your sender reads the response.

From your side, delivery failed. From theirs, the work is done.

A timeout tells you what you know. It says nothing about what the receiver did. So you retry, and the only thing standing between your customer and a second parcel is whether the receiver can recognize that this is the same thing again.

I ran into this while documenting the webhook module of Semitexa, the PHP framework I'm building. The mechanics were fine. What turned out to be hard was the vocabulary: "the key" meant three different things depending on who was asking.

One key, three questions

When people say "make it idempotent", they usually mean one key. But there are three separate questions:

Publication identity: did we already queue this outbound intent for this endpoint?
Event identity: did the receiver already record this event?
Business identity: is the effect already done, one shipment for this fulfilment intent?

For the example, that could be order:42:confirmed:v1, evt-order-42-v1, and a business rule. They protect different things, and mixing them up fails in two opposite directions:

A fresh key on every retry and the receiver can never recognize the repeat.
One key for everything about order 42 and the next legitimate shipment (a replacement, a second confirmation) gets swallowed as a duplicate.

The rule I ended up writing down: the key describes what may happen once, and it has to survive every attempt at that same thing.

Retry the right failures

Not every failure deserves another attempt. The policy we settled on:

Result	Decision
2xx	delivered
408, 429	retry if attempts remain
other 4xx	permanent rejection
5xx, timeout, no status	retry with exponential backoff and jitter, within a budget

A 400 is the receiver telling you the request is wrong. Sending it again ten times is just noise. A 503 or a timeout is the opposite: you don't know, so you ask again, and the receiver's memory makes asking again safe.

"Duplicate" is not "completed"

This one is quiet. The receiver gets the event, records it in its inbox, and crashes before creating the shipment. Your retry arrives. The inbox finds the record and says: duplicate, ignore.

The shipment never happens, and every log line looks healthy.

An inbox match tells you the event was seen. It does not tell you the work was done. The recovery decision has to look at business state, not only at the inbox. Where the action is a local database write, the completion record and the business update should commit together. Where it's an external side effect, you need the recipient's own idempotency mechanism or an explicit reconciliation path.

A lease protects the record, not the request

Delivery workers claim a record with a lease. Suppose a worker sends the HTTP request, then loses its lease before writing "delivered". A well-behaved worker won't overwrite a record it no longer owns, and ours doesn't. Good. But the request has already gone out. The receiver may already have acted.

The lease coordinates your bookkeeping. It cannot retract anything on the other side. Which brings it back to the receiver: the repeat has to be recognizable there, by the event identity, and the effect has to be protected where it happens, by the business identity.

What I'd check in any integration

Can you name all three identities for your most important webhook?
Does a retry carry the same event identity as the first attempt?
If the receiver records and then crashes, what finishes the work?
Do you inspect business state before you replay anything by hand?

If question 3 has no answer, that's the one I'd fix first.

Which of the three identities does your integration actually store today?

The longer version, with the retry ranges, the inbox key format and the recovery cases, is on the Semitexa blog: Your Webhook Was Delivered Twice. Now What?

Your AI agent doesn't understand your codebase. It greps it.

Taras Hanych — Mon, 05 Oct 2026 12:30:00 +0000

Before touching a class, a careful developer asks one question: who depends on this?

An agent answers it the only way it can. It runs a text search, reads whatever comes back, and decides the change is local. Most of the time that's fine. The times it isn't are the expensive ones.

What grep can't see

I've been writing PHP for over 18 years, and the agent-written bugs that cost me the most had the same shape. The edit looked local. The nearby tests passed. Something three modules away broke.

In a modern PHP app a lot of wiring never appears as a string you can search for:

A handler is connected to its payload by an attribute, not by a call.
An event listener is discovered at boot by scanning, so nothing "calls" it.
A template reads a field by name, so renaming a property breaks a page that never imports the class.

Grep finds the string. It doesn't find the edge. So the agent does what a cautious person does with a flashlight in a dark warehouse: it reads more. Half the project lands in context "just to be sure", the answer gets slower and more expensive, and it is still a guess.

Give the agent a map instead

While building Semitexa, my PHP framework, I stopped asking agents to rebuild the structure from text on every task. The framework keeps a project graph: real edges between classes, collected from the same attributes and conventions the runtime itself uses. Edges like implements, handles, serves_route, returns.

Before an edit, the agent asks two questions:

bin/semitexa ai:review-graph:query --usages=<Class>
bin/semitexa ai:review-graph:impact <Class>

The first lists what points at a class. The second walks outward and returns the blast radius: the routes, handlers and templates downstream of a change. It comes back as data, so the agent acts on it instead of guessing.

What changed

The side effect I liked most wasn't accuracy. The agent stopped reading half the project. With the impact list in hand it opens the files that matter and leaves the rest alone. Less context, better decisions.

It also changed code review. "What else did this touch?" used to be a question I answered by reading the diff and remembering the codebase. Now it's a query.

The trade-offs

A map has its own failure modes, and they're worth being honest about.

It goes stale. A graph built once describes code that no longer exists five edits later. Ours refreshes by content hash when a query runs, and says so when it can't.

It has blind spots. Anything wired dynamically, like a class name built from a string, is invisible to a static scan. The useful behaviour is for the graph to say what it could not see instead of pretending coverage is complete. An impact report with an "unknown" section is more honest than a clean one.

It is only as good as the conventions. The graph works because the framework has one way to wire a handler and one way to declare a route. In a codebase where routes come from YAML on Monday and attributes on Friday, there are no clean edges to collect. That is a big part of why I care about frameworks having one way to do each job.

Grep still has a job

I use grep every day, and so does the agent. It is the right tool for finding text. It is the wrong tool for understanding a system, because a system is made of relationships, and relationships are exactly what text search throws away.

If you run agents on a large codebase, here is something cheap to try even without a framework: generate a rough dependency list for the area being changed and put it in front of the agent before it starts editing. Watch how much less it reads.

How do your agents judge the impact of a change today: tests, grep, a map, or trust?

I'm building Semitexa in the open. The project graph is described in more detail here: Project Graph in Semitexa.

Your AI Agent Fixed the UI. Where Did the Screenshot Go?

Taras Hanych — Fri, 02 Oct 2026 12:30:00 +0000

Picture a normal afternoon with a coding agent. It fixes a broken table layout, runs the checks, and opens a PR. To make review easy, it attaches a before/after screenshot. You glance at it, the table looks right, you approve.

Now the question nobody asked in that review: where is that screenshot hosted?

What PixelLeak found

Glow Labs published research they call PixelLeak this week. The mechanism is almost boring.

GitHub lets you attach an image to a PR comment by dragging it into the browser. There is no equivalent for a CLI, which is where coding agents live. An agent that wants to show the reviewer a screenshot hits a wall. Rather than fail, agents found a workaround: create a public repository under the developer's personal account, push the image there, and link to it from the PR. Some teams used an open source helper that does the same thing.

Glow counted over 13,000 internal images in 900+ public repositories, from more than 300 organizations. The screenshots showed customer billing records, internal treasury and settlement consoles, money movement screens, and features that hadn't shipped yet.

The agent did its job

What bothers me most: there is no villain in this story. Nobody told the agent to publish anything. It was told, more or less, "show the reviewer what you changed". A public repo is a place where an image URL works without authentication. From the agent's point of view, that is a perfectly good solution.

We spend a lot of energy on what an agent may change in the code: which files, which commands, which branches. We spend much less on where its byproducts go. Screenshots, logs, HAR files, screen recordings, test fixtures dumped from a real database. None of those are code, so none of them go through the same review. And a screenshot of an internal tool is often more sensitive than the diff it documents.

What I'd put in place

1. Treat review evidence as data. A screenshot of a billing screen is customer data, the same as a database dump. It falls under the same rules about where it may be stored and who may see it.

2. Give the agent a sanctioned place. If there is a private, approved location for evidence (an artifact store of your CI, a folder inside the project that never leaves your infrastructure), the agent has no reason to improvise. Agents improvise when the obvious path is blocked.

3. Make "I couldn't attach it" a valid outcome. The workaround happened because failing felt worse than succeeding creatively. Say in your agent instructions, and ideally enforce in tooling, that "here is the local path, I could not upload it" is a complete answer.

4. Restrict what the agent's credentials can do. If the token the agent uses cannot create public repositories, this whole class of leak is gone. That is a much stronger guarantee than a sentence in a prompt.

5. Audit today. Look at your GitHub account and your team's accounts for repositories nobody remembers creating, especially ones full of PNGs.

Where this sits in my own work

I'm building Semitexa, a PHP framework designed for working with AI agents. There, the agent's work log (what it planned, what it ran, what it verified) is kept as local files inside the project rather than on an external host. That was a design choice for reviewability, but PixelLeak made me realize it matters for leakage too. Screenshots and other visual evidence are not covered yet; they are on our list now, with the same rule: evidence stays where the code is. The longer version, with a test matrix for the refusal path, is on semitexa.com.

Your turn

How does your team handle visual evidence from agents today? Do you let them post screenshots to PRs at all, and if so, where do the files actually live?

AGENTS.md doesn't work. Here's what did.

Taras Hanych — Wed, 30 Sep 2026 12:30:00 +0000

I spent a long time trying to make AI coding agents follow project rules through instruction files: AGENTS.md, CLAUDE.md, a rules folder. For a handful of basic instructions it works. Put your whole development "bible" in there and it falls apart.

The pattern is probably familiar. The agent breaks a rule, apologizes, promises it won't happen again, and breaks it again two changes later. It isn't being lazy. A rule in the prompt is a wish: it competes with everything else in the context, and the longer the session, the weaker it gets.

What actually worked

While building Semitexa, an open-source PHP framework designed for agent-driven development, I moved the rules out of the prompt and into a command. The only instruction the agent gets about rules is this:

Check every code change you make with ai:verify. If it lets you pass, move forward.

ai:verify looks at what changed and runs the lint and the tests that matter for that diff, plus the structural checks: where logic is allowed to live, what may call what. When it fails, the agent gets a concrete message about the thing it just did.

Three things changed:

The rules stopped competing for context. Adding a constraint no longer makes the prompt longer, so I can have as many as the project needs.
Failures became specific. "Handler returns a raw Response" is something an agent can fix in one step. "Follow the architecture" is not.
The agent got better over the session. The feedback arrives right after the mistake, not at review time, and more and more often the next change passes on the first try.

What the instruction file is still for

I didn't delete AGENTS.md. It got short. Now it's a map: where things live, which commands to run, and the one rule above. Anything that can be checked moved into the check. Anything that can't be checked (naming taste, whether an abstraction pulls its weight, whether the change matches the intent of the ticket) stays with human review.

The trade-off

A check costs more to write than a sentence. Some rules are genuinely fuzzy and never become checks. But every time I noticed myself writing the same review comment twice, it turned out the rule was never fuzzy, just unwritten. Those are the ones worth turning into code first.

Your turn

Where do your project rules live today: in instruction files, in CI, or in reviewers' heads? And has anyone found a good way to measure how often an agent actually follows an instruction file?

From Idea to First Customer: How Semitexa Shortens Time to Market

Taras Hanych — Mon, 28 Sep 2026 10:40:15 +0000

The first release of a business product has one job: help a real customer complete something valuable. Every week spent rebuilding common software foundations is a week before you can learn from that customer.

The clock stops at a customer outcome

A deployed homepage is a milestone. A usable business is a different one. Imagine a client portal: a customer signs in, submits a request, sees its status, and receives an update when the team acts. The team can see who owns the request and respond. That complete loop creates value and produces feedback worth acting on.

Time to market is the time until that loop works for its first customer. It includes product decisions, implementation, review and release. The shorter that path, the sooner a founder can validate demand, refine pricing and find out what customers actually need next.

Most launch delays hide between the features

The visible screen is often the easy part. A real client portal also needs identity and permissions, persistent data, an interface people can use, notifications, background work and a way to check that one customer's information stays with that customer. Teams can spend their early budget joining these pieces before they get to the workflow that makes the product distinct.

Semitexa addresses that integration work with a coherent set of modules and conventions. Its Framework has typed routes and handlers, data access, authentication and authorization, tenant context, events, queues and API capabilities. Its Platform provides reusable interface building blocks. The ecosystem describes the OS as the experience layer, Platform as the interface layer and Framework as the execution layer. Each layer gives the team a clearer starting point for a different part of the product.

These capabilities still need product choices and configuration. Their value is that the team can make those choices around an existing structure, then spend more of its time on the customer journey.

Build the differentiator on a connected foundation

For the portal example, the differentiator might be how requests are assessed, routed and resolved. Semitexa lets a team focus on that flow while using established paths for the surrounding work:

Move from screen to behavior. A page generator can scaffold the payload, handler, resource and template together, so the first interaction has an application path behind it.
Keep customer boundaries visible. Tenant resolution and tenant-aware data patterns give multi-customer products a place to express ownership early.
Let work continue after the response. Events and queues provide a path for notifications and longer tasks without making the customer wait on the page.
Expose the same operation where it is needed. Typed API routes can support other clients and integrations as the product grows.

You can inspect these ideas in the running Framework Demo: scaffolding, tenant data isolation and queued work each have their own walkthrough. The examples are useful because a buyer can look past a feature list and see the implementation shape.

Release one complete workflow first

A focused first version of the portal could be deliberately small. Let a customer submit one request type. Let the team review it and change its status. Show the change back to the customer and send one notification. Put access rules and data ownership around that path. Then invite a real customer to use it.

That sequence gives a team something more useful than a large unfinished feature list: a working transaction to observe. The first conversations will reveal whether the request form asks the right questions, whether the team needs another status, and which update customers value. Semitexa's structure helps the team change the application without starting a second architecture each time the product learns.

The fastest launch is rarely the one with the most features. It is the one that reaches a trustworthy customer outcome with the least avoidable construction along the way.

Speed matters after the first release, too

Going live early helps only if the team can keep improving the product. Semitexa includes project-aware inspection, dependency impact queries and focused verification commands. Those tools help developers understand what a change touches and check it before release. They do not replace testing or product judgment; they shorten the distance from a customer observation to a reviewable change.

This is why Semitexa is a strong route to market for customer portals, SaaS workflows and operational software. The product's first useful path can be assembled from existing application capabilities, while the team keeps ownership of the business rules that make the venture worth building.

Start with the first customer, not a feature inventory

If you are planning a product, describe the first person who will use it and the one job they must be able to finish. Add what happens immediately afterward: who reviews it, what data belongs to whom, and what message needs to be sent. That is enough to shape a useful first release and identify which Semitexa capabilities belong in it.

Bring us that workflow. We can turn it into a concrete launch scope, show the technical path and make the next decision about your business easier.

What must your first customer be able to do?

Tell us about the workflow, the people involved and the launch goal. We will help you find the shortest credible path to a working product with Semitexa.

Discuss your project

Explore the Framework Demo

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

The Tenant Must Travel with the Work

Taras Hanych — Mon, 28 Sep 2026 10:39:53 +0000

The browser knows which customer is working. The queue knows that something needs doing. A reliable SaaS application has to preserve the connection between those two facts.

The request ends before the responsibility does

Imagine a customer uploading a product image. The application accepts it, schedules a thumbnail, and returns a success response. A worker will finish the expensive part later. To the customer, this is one action: “prepare my image.” To the software, it is already two executions.

The second execution may start after the browser tab has closed. It may run in another process. The hostname that identified the customer is gone, along with the request that carried it. Yet the thumbnail still belongs to the same organization, under the same business rules.

This is an illustrative scenario, but the architectural boundary is real. Moving work into a queue also moves responsibility for its context. A job can arrive intact and still arrive without enough information to run correctly.

A perfectly delivered message can be incomplete

A message containing an asset ID and a transformation name tells a worker what to process. Depending on the application, it may leave other questions unanswered: which organization’s configuration should apply, which locale should an accompanying notification use, and which environment does this work belong to?

Those answers might be recoverable from the asset. That can be a valid design. The fragile version is the one where each downstream service guesses differently, or reads whatever “current tenant” happens to be left in memory. Local testing with one customer rarely challenges that assumption. A shared worker serving many customers will.

Adding a tenant field to a database table addresses one part of the design. Preserving the execution context across a queue is another. Semitexa makes that handoff explicit with a shared tenant context and a serializer at the message boundary.

Make the context part of the handoff

TenantAwareJobSerializer::wrap() reads the current context from TenantContextStore. For a concrete, non-default tenant, it adds an envelope under _tenant. The receiving side can extract that envelope and rebuild the context before application work begins.

Resolve: establish the tenant for the incoming execution.
Attach: serialize the supported context into the message.
Restore: recover that context at the worker boundary.
Execute: run the operation with an explicit tenant context available.
Clear: end the context’s lifetime when the execution finishes.

The queue separates two executions. The envelope connects their tenant context; the execution lifecycle owns cleanup.

An illustrative wrapped payload looks like this. The application fields are examples; _tenant and its fields follow the serializer’s current format:

{
  "assetId": "image-42",
  "variantKey": "thumbnail",
  "_tenant": {
    "tenantId": "acme",
    "strategy": "subdomain",
    "locale": "en",
    "environment": "prod"
  }
}

The implementation serializes the organization ID and resolution strategy, plus locale and environment when those layers are explicitly present. It does not serialize every possible context layer. A custom layer needs an intentional propagation design of its own.

There is also a deliberate default case: when no context exists, or the organization is the default tenant, wrapping leaves the payload unchanged. Consumers therefore need a policy for messages without _tenant. A task that requires an organization should reject missing tenant identity at its boundary.

This already has a job in Semitexa

The media package provides a concrete example. MediaQueueDispatcher wraps a serialized transformation message before sending it. On the receiving side, MediaWorker::processPayload() calls unwrapAndRestore() before reconstructing the media message and processing it.

Unwrapping removes the envelope from the application payload. Restoring places the recovered context into the store’s CLI fallback. The transformation message keeps its own domain shape, while services that consult the context store have a tenant available during execution.

The media transformation path also passes the asset’s tenant ID explicitly when resolving collection policy and generating a variant. That detail matters: the queued context and the persisted asset identity play distinct roles. Application code still has to enforce the relationship between them wherever that relationship controls access or storage.

This is the concrete problem Semitexa addresses: the HTTP request can disappear without making an integrated background operation reconstruct tenant context from ambient process state. The producer and consumer share one envelope format and one restoration mechanism. Custom queue paths must wire those mechanisms into their own execution boundary.

A worker must also know when to forget

Now imagine the same worker processes a second message. It has no tenant envelope. If the first job’s context remains in memory, the second job may observe the first customer’s identity. Correct propagation into one job has become incorrect propagation into the next.

This is where tenancy meets the long-running PHP lifecycle. In a Swoole coroutine, Semitexa’s tenant store reads coroutine-local state. Outside a coroutine, it uses a process fallback. Those storage choices support different execution environments and require a clear end to each unit of work.

TenantContextStore registers cleanup with PerRequestStateRegistry when context is set. Its cleanup callback clears the context of the current execution: the coroutine-local slot inside a coroutine, the process fallback outside one. The surrounding runtime must actually invoke that lifecycle at the appropriate boundary.

The serializer alone does not provide that boundary. In particular, unwrapAndRestore() sets the fallback when an envelope exists; a message without an envelope does not make that method clear an earlier fallback. A custom worker loop must explicitly ensure cleanup, including on exceptions and early returns. A coroutine consumer must establish context in the coroutine’s own store rather than assuming the CLI fallback is visible there.

Preserve the tenant across the handoff. End its lifetime after the work. Both steps belong in the design.

Put each guarantee where it can be enforced

Once the context travels reliably, the rest of the application has a stable input. It still needs to use that input correctly.

Resolution determines which organization an execution refers to.
Authorization determines whether the actor or job may perform the action for that organization.
Data isolation scopes queries, cache keys, storage paths, and other resources where the application accesses them.
Propagation and cleanup preserve context across handoffs and prevent it from surviving into unrelated work.

The envelope carries identity; it does not prove permission. Queue ingress must be trusted or validated, tenant-owned records must be checked, and tenant-sensitive operations need an explicit policy for absent context. Semitexa supplies the context mechanisms. An application earns its isolation guarantee through the boundaries that consume them.

Test the handoff with two customers

A useful test goes beyond proving that one message round-trips through a serializer. Process work for tenant A, then tenant B, in the same worker. Follow both with a message that has no tenant envelope. Check what each operation can observe. Repeat the sequence with a failure during A’s work, so cleanup has to survive an exception.

At the serialization level, Semitexa’s tenancy package includes dedicated propagation tests. At the application level, test the effects: which configuration was selected, which records were accessed, and where the output was stored. Also check any locale or environment values the workflow promises to preserve. These are acceptance criteria for an integration, not a claim that a serializer test proves every application safe.

The larger lesson is useful well beyond media processing. Exports, notifications, and scheduled work all cross moments where the original request is no longer available. Making tenant context explicit turns those moments into boundaries that can be inspected and tested. A customer’s action can then continue after the response, with its ownership still accounted for.

Follow the lifetime of the work.

Explore tenant propagation in the Framework guide, then see why execution boundaries matter in a process that stays alive.

Explore tenant propagation

Read about long-running PHP

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Three Layers, One Workflow: OS, Platform, and Framework

Taras Hanych — Mon, 28 Sep 2026 10:39:30 +0000

A good business tool needs a place to work, an interface that makes the work clear, and a system that carries it out. Semitexa gives those three jobs distinct names.

Three layers, three questions

Think about a person reviewing an approval. They need to find the task, understand the details, and submit a decision. It is tempting to call all of that “the app.” Separating the responsibilities makes it easier to design the experience and to reason about the code behind it.

Start with the human need, then decide which layer owns each part. The arrows show a design conversation, not a requirement that every request passes through three separate services.

OS: where work has a home

Semitexa OS is the experience layer. Its job is the shape of a working day: how someone finds their projects, changes focus, and keeps context while moving between tools. A useful OS decision might be whether an approval is visible beside the project it belongs to, or how the workspace helps someone return to an unfinished task.

That is a product question before it is a component question. A polished button cannot repair a workflow that leaves people lost. The OS site presents this operating surface as a product vision; the layer map describes the intended responsibility, not a claim that every possible workflow is already shipped end to end.

Platform: how the work is presented

Semitexa Platform is the interface layer: reusable fields, data views, product shells, and interaction patterns. If the same kind of approval appears in several products, this layer is where the visual grammar should remain consistent. The Platform showcase demonstrates server-owned rendering, components, deferred regions, and live updates.

Reusability is useful only when it clarifies the task. A field should make its label, help, validation, and state legible. A data view should make scanning and acting on a row predictable. Platform supplies that common language while each product keeps its own purpose.

Framework: how the decision runs

Semitexa Framework is the execution layer. In its typed PHP flow, a payload describes an incoming request, a handler makes the application decision, and a resource returns the result. Server-rendered pages, events, tenancy, and long-running work can share that explicit architecture.

For an approval, application code still has to check who may act, apply the business rule, store the result, and decide whether an event should follow. A reusable interface does not make that decision for the server. The Framework site lets you inspect working routes and demos when you want to see how the underlying request and response fit together.

One workflow, three decisions

Imagine an approval inbox. This is an illustrative feature, not a claim that a shared inbox is already deployed across all three sites.

Experience: place the inbox where a person can find it in the context of their project, and make the next action obvious.
Interface: show the request in a readable data view, present the decision with a consistent control, and explain any validation error.
Execution: accept the action through a typed route, check permission and state in application logic, then return the updated result or publish follow-up work.

The boundaries help when a feature changes. If people cannot find the inbox, revisit the experience. If every inbox looks different, revisit the interface. If the action can be applied twice or by the wrong person, revisit execution. The separation turns a vague “the app feels wrong” into a question a team can answer.

Where to start exploring

Begin with the layer that matches your question. Explore the OS vision to see the working environment, the Platform showcase for reusable interface patterns, and the Framework installation guide when you are ready to trace or build the PHP flow. These sites currently show different parts of the ecosystem; the three-layer map gives them a shared design vocabulary.

Follow the question to the right layer.

Explore OS

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Long-Running PHP: Inside the Semitexa Runtime

Taras Hanych — Mon, 28 Sep 2026 10:39:00 +0000

The first request works. The second remembers more than it should. Keeping a PHP application alive makes its lifetimes part of the architecture: which objects should survive, which data belongs to one execution, and what happens while two requests overlap? Semitexa was designed from day one around those questions.

Designed for long-running PHP from day one

Imagine a dashboard showing an order as it moves from payment to fulfillment. The first page should arrive quickly. A slow recommendation service should not hold up the order details. A background job should be able to publish progress. Several people may be watching, each with their own session and permissions.

That application benefits from more than a faster request handler. It needs reusable infrastructure, isolated execution state, efficient waiting, live delivery and a way to see what is happening inside the server. Semitexa treats those needs as parts of the same runtime design.

Semitexa was created for the long-running execution model from the beginning. The worker is a first-class lifetime. The container distinguishes shared services from execution-scoped objects. Request context is carried through the framework. Coroutines, background work and streamed HTML have a place in the architecture.

The practical advantage is consistency. You can follow a typed payload into a handler, resolve dependencies with explicit lifetimes, produce a resource, and render or stream it using the same application model. The framework can make decisions at startup because the resulting application will serve many executions.

Other PHP runtimes also keep applications in memory; FrankenPHP's worker documentation is a useful introduction to that broader model. This article examines Semitexa's own Swoole-based implementation. Its strength is how the framework's pieces are designed to work together within that model.

The worker lives longer than the request

In a conventional PHP-FPM deployment, a worker process can already serve many requests. The application is normally initialized within each request's PHP execution, with ordinary userland request state torn down afterward. Long-running application servers keep the initialized application itself available across requests.

OPcache and application persistence address different work. OPcache caches compiled script bytecode. A persistent application can also reuse its bootstrapped service graph and discovered metadata. Neither mechanism makes database queries, remote APIs or expensive business logic disappear.

Worker starts   → discover and build      Warm application
Request A       → its context + handler   Response A
Request B       → its context + handler   Response B

One worker can reuse its application while each request receives its own execution state. With coroutines, request A and request B may overlap while waiting for I/O. This is an architectural diagram, not a timing measurement.

The useful distinction is ownership. A service containing stable behavior can live with the worker. The current customer's identity belongs to an execution. A database connection is a resource to borrow for bounded work. A cross-worker counter needs an explicitly shared store.

Lifetime	Examples	Design consequence
Worker	Shared services, container metadata, handler prototypes	Reuse them; keep request identity out of their mutable fields.
Execution	Handler clone, request, auth, tenant and locale context	Resolve them for the current execution and release them afterward.
Borrowed operation	Database or Redis connection	Return it after use; bound how long a caller can wait.
Explicitly shared state	Database records, Redis data, selected Swoole tables	Choose storage and atomic operations appropriate to the sharing boundary.

A PHP static property is local to its process and can survive many executions. It is therefore a poor place for “the current user,” and it is not automatically a counter shared by every worker. Understanding both boundaries prevents two very different classes of mistakes.

Try it: a persistent worker, a fresh handler

The following values are produced by the PHP handler serving this article. Its $handled property starts at zero and is incremented when handle() runs. Semitexa's execution-scoped resolution supplies a fresh handler clone for the next request.

▶ Run the live demo — Which state survived?

Run it again. The handler counter should still be 1. You may see the same worker process ID, or another one when the server distributes requests across workers. A reload or deployment can also change the process ID. A repeated ID with a fresh counter illustrates the two lifetimes directly.

This is an actual PHP result, with caching disabled for the response. It is a small demonstration of handler resolution; it does not by itself prove concurrent tenant isolation or measure throughput. We will run the relevant concurrency tests later.

PHP · the handler's scalar state starts fresh on each resolved clone

// BlogArticleHandler: excerpt from the handler serving this page.
// #[AsPayloadHandler] makes the handler execution-scoped.
private int $handled = 0;

// Inside handle(), when this article is requested:
return $resource->withRuntimeProbe(
    workerPid: (int) getmypid(),
    executionCount: ++$this->handled,
    renderedAt: gmdate('Y-m-d\TH:i:s\Z'),
);

The handler does not contain a counter-reset instruction. The lifetime is established when the container resolves it. If an application deliberately keeps that clone in a global variable, or puts the counter in a static property, it has chosen a different lifetime.

A dependency container that knows what should survive

Semitexa's container performs module discovery, attribute scanning, contract resolution, injection analysis and graph construction during its build. It stores shared service instances and execution-scoped prototypes, then seals registration. Each HTTP worker builds its container during startup.

That moves structural work out of the ordinary request path. The worker can reuse known bindings and injection metadata while resolving the objects needed for the next execution. The payoff is less repeated bootstrapping and a clear place to diagnose wiring problems.

Two injection attributes make the lifetime distinction visible in application code. #[InjectAsReadonly] supplies a worker-scoped dependency. #[InjectAsMutable] supplies execution-dependent values or services when the scoped object is cloned. Payload handlers, event listeners and pipeline listeners imply execution scope; other applicable services can declare #[ExecutionScoped].

PHP · property injection expresses which dependency belongs to which lifetime

// Properties on an execution-scoped payload handler:
#[InjectAsReadonly]
protected SiteBlogCatalog $blog;

#[InjectAsMutable]
protected Request $request;

// The catalog is reusable across executions.
// Request is resolved from the current execution context.

The shared attribute describes the injection lifetime; it does not make every property inside the injected object immutable. A shared service still needs appropriate state discipline. Similarly, PHP cloning is shallow: arbitrary mutable child objects do not become independent just because their parent was cloned. Execution-dependent dependencies should use the framework's scoped resolution.

You can inspect the implementation in ContainerBootstrapper and SemitexaContainer. The latter's resolution path clones scoped prototypes and injects the current context. This is the mechanism behind the counter above.

Let requests overlap without sharing their identity

A request waiting for a database response should not have to monopolize a worker that could serve another request. Semitexa's server enables Swoole coroutines and runtime hooks before creating the HTTP server. Supported blocking operations can yield so another coroutine can make progress.

This is especially useful for I/O-heavy pages, upstream API calls and long-lived streams. It does not turn a CPU-heavy PHP loop into parallel work, and runtime hooks only cover supported operations in the installed Swoole build. CPU-bound work still needs an appropriate process or job strategy.

Overlapping requests make isolation more demanding. Clearing a global “current user” at the end of a request cannot protect another request that was already running while the first one yielded. The current identity must be attached to the execution that owns it throughout the overlap.

Semitexa's ExecutionContext carries request, session, cookies, tenant, auth and locale values. The container stores those bindings through CoroutineLocal, which uses Swoole's coroutine context during coroutine execution. Resolving a mutable dependency after a yield therefore reads the current coroutine's context.

The container itself remains shared. The execution bindings do not become an ordinary field on that shared container. This separation is one of the most important strengths of a framework designed around persistent, concurrent workers.

Child coroutines have a deliberate boundary too. A new child does not automatically inherit its parent's execution context. Framework code that needs propagation captures the context and applies it explicitly:

PHP · explicit propagation when writing a custom coroutine integration

// Runtime integration code with an execution-context-aware container.
$snapshot = $container->captureExecutionContext();

\Swoole\Coroutine::create(function () use ($container, $snapshot): void {
    $container->runWithExecutionContext($snapshot, function () use ($container): void {
        // Resolve context-dependent services inside this callback.
        $request = $container->captureExecutionContext()->request;
        // Perform the child operation using its explicit context.
    });
});

runWithExecutionContext() restores the previous bindings in a finally block. The snapshot carries references to context objects; it is not a deep copy that makes arbitrary shared mutations safe. Ordinary payload handlers receive their dependencies through injection; this lower-level API matters when implementing runtime integrations.

The CoroutineLocal implementation also provides a process-local fallback for CLI execution. Request lifecycle cleanup remains necessary there, where one process may perform several executions without Swoole coroutine teardown.

Reuse connections with clear ownership and bounded waiting

A persistent runtime can keep useful database connections open. It also needs to prevent two executions from accidentally treating the same connection as their own transaction. Connection reuse becomes an ownership problem as well as a performance opportunity.

Semitexa ORM's coroutine-aware pool uses a bounded Swoole channel. A caller borrows a connection, uses it and returns it. Pool acquisition has a timeout and reports exhaustion. The pool can recover abandoned borrows when a coroutine ends, and it tracks events such as discards and exhausted waits.

That gives the application an explicit capacity boundary. When available connections are occupied, callers wait within a limit instead of creating an unbounded number of connections. Pool capacity is per pool in a worker process; size the deployment against the total number of workers and the database's connection budget.

Returning a connection includes transaction hygiene. If PDO reports an open transaction, the pool attempts a rollback before reuse. If that cleanup fails, the connection is discarded. This prevents a later borrower from inheriting an unfinished transaction on that path. The check relies on PDO's transaction tracking, so raw SQL transaction commands are not a substitute for the managed transaction API.

The implementation also recognizes process changes so inherited connection resources are not casually reused after a fork. These details matter because the resource outlives any single request.

The ORM ConnectionPool source shows the checkout, return, timeout and reclaim paths. The application-level lesson is straightforward: keep borrowed resources close to the work that uses them, release them promptly, and avoid holding a database connection while waiting on an unrelated remote service.

The same runtime can deliver the page and keep it alive

The dashboard from the opening example has several useful moments to render. Order details are ready now. Recommendations arrive later. Fulfillment progress changes while the visitor is watching. Semitexa's rendering model can represent each moment without relocating the business rules into the browser.

A PHP handler fills a resource and Twig renders the initial HTML. A deferred region can arrive when its slower work finishes. SSE can carry subsequent updates. Coroutines let supported I/O waits yield while the worker handles other work; the connection and its resources still have a cost that the deployment must budget.

This combination is a practical runtime strength: reusable application services, execution context and server rendering participate in one flow. A shipping rule can remain in PHP while its result appears in the first response, a deferred block or a later live update.

Our Server Side Rendering 2.0 guide contains a working shared-template example. The Streaming SSE guide explores live delivery. Read them as concrete applications of the lifetime and concurrency model described here.

A live connection also crosses operational boundaries. Proxies need suitable buffering and timeout settings. Clients need reconnection behavior. Authentication and tenant isolation still apply to streamed content. Semitexa provides framework mechanisms for live delivery; a deployment must configure the network path around them.

A long-running worker must also know how to stop

Startup is only part of a persistent runtime. A deployment eventually replaces workers. Timers may still be firing, an SSE connection may be open, and a coroutine may be waiting on a socket. A complete lifecycle has to account for that work.

Semitexa exposes server lifecycle phases around startup and shutdown. Its current Swoole configuration enables asynchronous reload with a finite drain window. On worker exit, the bootstrap raises a drain signal, clears timers and attempts to cancel parked coroutines. It reports coroutines that refuse cancellation so a stalled shutdown has evidence.

This is bounded shutdown, not a promise that every in-flight operation completes. Some driver calls cannot be interrupted immediately, and Swoole may force termination after the configured wait. Work that must survive a worker replacement needs durable job handling, appropriate retries and idempotency.

The same ownership principle appears at smaller boundaries. HTTP handling resets registered per-request state and disposes request-scoped bindings in cleanup. Queue workers perform per-message cleanup. Scheduled execution restores a previous tenant context after a tenant-bound run. A process can stay alive while the framework closes an individual unit of work.

These mechanisms are visible in SwooleBootstrap and its server configuration. For application developers, they provide explicit places to attach lifecycle behavior and explain why an unbounded background loop needs an exit strategy.

Inspect the behavior and make the boundary executable

Long-running behavior becomes easier to trust when you can examine more than a successful first response. Semitexa's development tooling connects route structure, active processes and recorded execution. The tools operate on the same application whose lifecycle you are investigating.

Terminal · inspect the article route and a source-linked development trace

bin/semitexa ai:ask route \
  --path=/blog/long-running-php-semitexa --json

bin/semitexa ai:observe ps

# In development, visit the article with ?__trace=1 first.
bin/semitexa ai:observe tail \
  --kind=http --name=BlogArticle --lines=4 --json

# Replace p-YOUR-ID with the request id from the journal.
bin/semitexa ai:observe show --id=p-YOUR-ID --source

Route inspection identifies the payload, handler, resource and template. Observatory lets you inspect process lifecycles and, for a traced development request, the recorded handler execution. Full traces and source views in this walkthrough require development mode.

The stronger isolation check is an interleaving test. Two coroutines install different request contexts, both yield, and then each resolves a context-dependent object. Each must still receive its own request. The core test suite also checks that a child starts without the parent's context and that explicit propagation restores the intended values.

Terminal · run the actual context isolation and lifecycle regression tests

# Run from the Semitexa development workspace with its Swoole runtime.
bin/semitexa test:run \
  packages/semitexa-core/tests/Unit/Container/SemitexaContainerExecutionContextIsolationTest.php

bin/semitexa test:run \
  packages/semitexa-core/tests/Integration/RequestScopedContainerLifecycleTest.php

These commands target tests in the development workspace; an installed distribution may not include that test tree. Coroutine cases require the Swoole extension and are skipped without it. Check the result for skipped tests as well as failures. The concurrent isolation test source shows exactly which boundary is exercised.

Performance needs its own evidence. Compare cold and warm behavior on the same workload, then measure latency under concurrency, memory over sustained traffic, database wait time and failure recovery. Avoid inferring an application-wide speedup from a counter or a hello-world route. Semitexa supplies mechanisms that remove repeated work and manage concurrency; the gain depends on where your application spends time.

When editing a development checkout, reload the running application before testing changed server code: bin/semitexa server:restart app. CLI checks such as ai:verify run in fresh processes and do not need that restart. That distinction is another direct consequence of the worker lifetime.

Build around the lifetimes the application actually has

Semitexa's runtime design gives a PHP application a coherent set of building blocks: a warm service graph, execution-scoped handlers, coroutine-local context, bounded connection reuse, live server-rendered output and explicit worker shutdown. Observability and regression tests make those boundaries inspectable.

That is the significance of designing for long-running PHP from day one. The execution model shapes how dependencies are declared, how a handler is created, how state is carried, how a connection is returned and how HTML reaches the browser. Each part has a defined place in the application lifetime.

Start with one real feature. Keep stable services reusable, put execution-specific data in the appropriate scope, keep resource borrowing short, and test the second request as carefully as the first. Then add the overlapping requests and live updates that make the runtime's strengths useful.

Build a PHP application that stays ready.

Install Semitexa, inspect one request, and follow its state from the worker to the rendered page.

Get started with Semitexa → Run the lifecycle example again

Implementation references are pinned to the core and ORM revisions inspected for this article. Runtime details and command options can evolve; consult your installed version's help and source when applying an example.

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

AI-Native PHP Development with Semitexa

Taras Hanych — Mon, 28 Sep 2026 10:38:33 +0000

An AI coding agent can produce a convincing patch. The harder question is whether it found the right code, understood the rule, and proved that the application now behaves correctly. AI-native PHP development with Semitexa gives that investigation a concrete foundation: an explicit execution path, a queryable project graph, observable requests, and verification the agent can run.

AI-native PHP starts with an application an agent can inspect

A developer reports: “Free shipping is broken.” Before changing a line, an agent has several questions to answer. Which route handles the request? Which policy calculates shipping? Is the browser displaying a server result or calculating its own? What happened for the failing order? Does “from $100” include $100 itself?

A repository can contain all the answers and still make them expensive to find. A string search returns references with different meanings. A class name suggests responsibility but does not prove it. A screenshot shows the wrong total without identifying the calculation. Even a successful request tells us only that execution completed.

Semitexa gives those questions named tools. Route introspection explains the request chain. Project Graph reports structural relationships. Observatory records execution. The agent can move from a user-visible symptom to a specific method with evidence at each step.

The roles remain clear: the agent reasons; Semitexa supplies an execution, inspection, memory, and verification environment. The framework does not decide the product requirement. The developer still owns the acceptance criteria and reviews the change. “AI-native” here means that an agent has useful, structured ways to discover and check the application it is editing.

Evidence	Question it answers	What it cannot establish alone
Route introspection and Project Graph	How is this feature connected?	Which path a particular request took
Runtime trace	Which instrumented steps actually ran?	Whether the business result was correct
Acceptance cases and tests	Did the result meet the stated rule?	Every possible input or deployment condition

Reproduce the bug: one cent makes the difference

Our requirement is deliberately small and unambiguous: standard delivery costs $12 below a $100 subtotal, and is free at $100 or more. There are no taxes, discounts, currencies to convert, or regional exceptions in this lab. The amounts are represented as integer cents.

Start with the faulty fixture at $100.00. Then try $99.99 and $100.01. Both neighboring cases behave correctly, which is why a quick check of an ordinary order could miss the defect. Finally, choose the corrected rule and repeat all three cases.

▶ Run the live demo — Free standard delivery from $100, inclusive

The controls submit a regular GET form. Semitexa hydrates a typed payload, runs the handler, and renders the result through Twig. The example also works with JavaScript disabled. The browser displays the amounts returned by PHP; it contains no second shipping calculation.

This is a controlled teaching fixture with two predefined implementations. Selecting “corrected rule” does not ask an AI model to generate a patch or edit a file. Keeping the faulty implementation available lets every reader reproduce the same mistake and compare it with the correct behavior.

The defect is a single comparison. In the faulty branch of DemoShippingRuleLab, the condition is:

PHP · the faulty fixture excludes the threshold itself

return $subtotalCents > 10000 ? 0 : 1200;

Finding that line is easy once someone tells you where it is. The useful engineering problem is reaching it from the symptom without guessing, then demonstrating that the correction satisfies the requirement.

Find the route before searching the whole repository

In a local Semitexa development checkout containing this Demo article, ask the framework for the route chain:

Terminal · route ownership and the payload's graph impact

bin/semitexa ai:ask route \
  --path=/blog/ai-native-php-development-semitexa --json

bin/semitexa ai:review-graph:impact \
  'Semitexa\Demo\Application\Payload\Request\BlogAiNativePayload' --json

The route query identifies a public GET endpoint, BlogAiNativePayload, its synchronous BlogAiNativeHandler, BlogAiNativeResource, and pages/blog-ai-native.html.twig. The graph impact query reports the handler one relationship away from the payload. These are results from the implementation of this article.

Typed payload       → handler    PHP lab service
Calculated result   → resource   Twig → HTML

The article's code path, combining route metadata with the handler source. This diagram is an explanation, not a live trace visualization.

Now the investigation has a narrow starting point. The handler's source shows its injected DemoShippingRuleLab service and the call to run(). That is the policy to inspect; the template is responsible for displaying its result.

Graph results have a scope. In the inspected build, the handler dependency query exposed its typed payload, resource, and interface relationships, but did not list the injected lab service. Reading the identified handler supplied that last connection. An agent should treat the graph as evidence about the edges it reports, rather than assume that an absent edge proves there is no dependency.

This becomes especially useful when a feature spans modules. Start from an actual route or symbol, follow the relevant relationships, and open the files that answer the remaining question. The Project Graph guide explores that structural workflow in more detail.

Observe the request that produced the wrong answer

Structure tells us where to look. Runtime evidence tells us whether the request reached that code. In your local development environment, open this article's route with the trace flag:

Development URL · request a full trace for the failing case

/blog/ai-native-php-development-semitexa?scenario=boundary&rule=buggy&__trace=1

Use the process journal to find the request, then inspect its source-linked trace. The request name is the payload class name; the process ID comes from the journal:

Terminal · inspect the recorded execution and its source

bin/semitexa ai:observe tail \
  --kind=http --name=BlogAiNative --lines=4 --json

# Replace p-YOUR-ID with the completed request's id.
bin/semitexa ai:observe show --id=p-YOUR-ID --source

The request used while preparing this guide returned HTTP 200 and recorded a pipeline.handler span whose source_ref was BlogAiNativeHandler::handle, with its full namespace. The source output included the actual call that passes the selected scenario and rule to the lab service.

Notice the distinction: the request completed successfully while displaying a wrong business result. HTTP 200 is not a shipping-policy test. Likewise, the handler span proves that the instrumented handler ran; it does not imply a separate span exists for every internal PHP method call.

A developer can inspect the same development environment through /__observatory and the waterfall at /__trace. Source views connect recorded steps to code without a second search through similarly named handlers. Those source slices are read from the current files, so they are most useful before the implementation changes; they are not an immutable historical copy of the code.

Full traces, source inspection, and replay in this walkthrough require development mode. Observatory also has a restricted production monitoring mode for lifecycle records, with different access and data limits. The public lab on this page exposes only its fixed shipping cases.

Correct the rule where the rule lives

The acceptance criterion includes the threshold itself. The corrected PHP expression is therefore:

PHP · free delivery includes an exact $100 subtotal

return $subtotalCents >= 10000 ? 0 : 1200;

In a real shipping policy, that is the implementation we would keep. This article retains both branches in the isolated lab so the comparison remains runnable. The expected amounts are stored separately as explicit acceptance cases; they are not calculated by calling the same shipping function and trusting its answer twice.

The handler coordinates the work and passes decided values to the response resource. This is the relevant call from the page's real handler:

PHP · handler excerpt, expanded for readability

->withLab($this->shippingLab->run(
    $payload->getScenario(),
    $payload->getRule(),
));

Twig owns the view: labels, amounts, selected options, and the visible comparison. The service owns the calculation. This separation reduces the number of places an agent must change and the number of competing implementations a reviewer must reconcile.

The same ownership principle matters when interfaces become more dynamic. A deferred region can receive a server-calculated result, and a live update can deliver newly rendered content without inventing a browser-side shipping policy. Our Server Side Rendering 2.0 article demonstrates shared templates and deferred blocks; the Streaming SSE guide follows live delivery.

One source of truth has a precise meaning here: one owner for the business rule, and one authoritative template for the view. Moving the comparison into Twig would blur that boundary again. Asking an agent to keep duplicated PHP and JavaScript pricing functions synchronized would preserve the duplication rather than resolve it.

Replay the handler with an explicit change of input

Once a request has a full trace, Semitexa can use it as the starting point for a handler replay. For this isolated lab, provide both inputs explicitly and select the already implemented corrected branch:

Terminal · re-execute the recorded handler with explicit lab inputs

bin/semitexa ai:observe replay --id=p-YOUR-ID \
  --mutate=scenario=boundary --mutate=rule=fixed

The replay we ran returned verdict: ok. Its resource contained the following lab values, shown here as a shortened selection from the output:

Observed replay output · selected lab fields, not the full envelope

{
  "scenario": "boundary",
  "rule": "fixed",
  "actualShippingCents": 0,
  "expectedShippingCents": 0,
  "actualTotal": "$100.00",
  "matches": true
}

Explicit inputs matter. This page's original hydration trace contained an empty payload snapshot, so it would be incorrect to claim that replay automatically preserved the selected form values. Here we know exactly which scenario we are rerunning because the command supplies it.

Replay also has a narrower execution boundary than a fresh browser request: it invokes the resolved handler with a hydrated payload and resource. It does not reproduce the complete HTTP, authorization, and rendering pipeline. Use it to inspect a handler result, then exercise the actual page to verify delivery and presentation.

The replay runner rolls back its managed database transaction and captures queue handoffs. Supported mail transport is withheld during the sandboxed run. Arbitrary outbound HTTP calls and LLM provider calls are not universally suppressed, so replay is not a blanket guarantee of external isolation. This lab performs no such calls and creates no orders.

Make the acceptance criterion executable

A plausible patch becomes a useful fix when the requirement survives independent checks. For our inclusive threshold, the three adjacent cases provide a compact specification:

Subtotal	Expected delivery	Faulty rule	Corrected rule
$99.99	$12.00	$12.00 · matches	$12.00 · matches
$100.00	$0.00	$12.00 · mismatch	$0.00 · matches
$100.01	$0.00	$0.00 · matches	$0.00 · matches

The article's test suite checks all six scenario/implementation combinations and the fallback for unknown inputs: seven tests and 25 assertions. A test for the faulty branch asserts that the lab exposes the mismatch; it does not approve that charge as correct product behavior.

Terminal · execute the acceptance cases and scoped framework checks

bin/semitexa test:run \
  packages/semitexa-demo/tests/Unit/Service/DemoShippingRuleLabTest.php

bin/semitexa ai:verify \
  --files=packages/semitexa-demo/src/Application/Service/DemoShippingRuleLab.php \
  --files=packages/semitexa-demo/tests/Unit/Service/DemoShippingRuleLabTest.php \
  --json

ai:verify selects applicable checks for the files under review. Its report is evidence about the checks it ran. The focused service tests establish the boundary behavior; a browser check additionally establishes that form inputs reach PHP, values render correctly, and the page remains usable.

Semitexa's long-running workers cache discovered classes and compiled templates. After changing the implementation, run bin/semitexa server:restart before testing the running HTTP server. CLI verification uses fresh processes and does not need that restart.

The product decision still comes first. If the requirement had said “strictly over $100,” the original comparison would be correct. An agent must resolve that ambiguity with the product owner or an authoritative specification. Neither a graph nor a trace can invent the intended meaning of a promotion.

Keep the evidence when the conversation moves on

Long investigations often fail at the handoff. The next session sees a modified file but loses the reason for the change, the failing input, and the hypothesis that was already disproved. The agent spends time reconstructing an investigation someone already completed.

Semitexa's ai:epic, ai:work, and ai:trace commands give ongoing work durable artifacts. ai:orient brings the active work and recent verification back into view. ai:context retrieves relevant prior context before an agent starts reading from scratch.

For this example, a useful handoff would preserve the inclusive-$100 requirement, the $112 failing result, the identified handler and service, the empty trace snapshot limitation, and the passing acceptance cases. “Investigated shipping” would preserve almost nothing.

The amount of process should fit the work. A focused correction can stay small. A change spanning several modules needs explicit tasks, dependencies, decisions, and a next step that another session can actually execute. The purpose is continuity: preserve the facts needed to continue without asking an agent to remember a conversation forever.

Evidence also needs freshness. A graph, a source view, or a passing test report describes a particular state of the project. After editing relevant code, rerun the checks that could have changed and record the new result.

Start AI-native PHP development with one real bug

The shipping mistake is small enough to understand in one sitting. The workflow scales because each step asks a specific question: reproduce the symptom, locate the route, inspect the relevant structure, observe execution, correct the owning rule, and verify the requirement.

Semitexa makes that sequence concrete through the application itself. An agent can query framework metadata, follow a source-linked runtime step, execute a focused test, and leave the evidence for the next session. A developer can review those same artifacts and challenge a conclusion at the point where it was made.

That is the useful promise of AI-native PHP development: a shorter, more inspectable path from “this behavior is wrong” to “here is the rule, the change, and the evidence that it now holds.” The strongest demonstration is an application you can run and question.

Try it on your own feature. Choose one reproducible request and write its expected result first. Start with bin/semitexa ai:orient --json, then ask for its route chain. Keep the investigation narrow enough that every proposed change can be connected to a concrete acceptance case.

Continue with the Semitexa installation guide, explore the development tooling package, or return to the shipping lab and test the boundary yourself. Commands in this guide reflect the development build used for the article; your installed version's --help and capability output describe its available options.

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Server Side Rendering 2.0

Taras Hanych — Mon, 28 Sep 2026 10:38:11 +0000

PHP began with a remarkably direct idea: the server knows the data, so let it build the page. Decades of richer interfaces have taught us what that model needed next. Semitexa combines one authoritative template with deferred blocks, live delivery, and explicit PHP boundaries. This article is a working example of that architecture.

Before SSR had a fashionable name, PHP was rendering pages

Server rendering is part of PHP's foundation. The PHP project's history traces its early development through form handling, database interaction, and syntax embedded in HTML. The request arrived at the server; PHP evaluated the dynamic parts; the browser received a document.

A familiar template from a later generation of PHP applications looked like this. HTML supplied the structure, and a block object supplied the values:

Classic PHP template · HTML with PHP expressions

<article class="product-card">
    <h2><?= $block->getTitle(); ?></h2>
    <p><?= $block->getDescription(); ?></p>
    <strong><?= $block->getFormattedPrice(); ?></strong>
</article>

The browser never executes $block->getTitle(). PHP has already replaced that expression with output before the response arrives. The PHP manual describes this mixture of HTML and PHP directly. The block object is a familiar architectural example, not a claim that the earliest PHP versions used this class design.

The short example shows the old shape of the code. For a title supplied as plain text, an actual application must also escape output for its HTML context:

PHP · escaping a plain-text title

<h2><?= htmlspecialchars($block->getTitle(), ENT_QUOTES, 'UTF-8'); ?></h2>

This model had a valuable property: one template described what the user would see. Links were links, form submissions reached the server, and the page contained useful content from the beginning. Its problems came from how applications were structured and updated. Templates could grow SQL queries and business decisions. A slow dependency could delay the entire response. Updating a small region often meant loading the whole page again.

Those limitations were real. The useful lesson was to improve the boundaries and the delivery of the page while preserving the clarity of a single rendering definition.

We gained richer interfaces—and another application to keep correct

Separate frontend applications solved important problems. Browser code could manage complex interactions, update local state, and provide experiences beyond a form followed by a full reload. APIs made it possible to serve multiple clients. Specialist teams could work and release independently.

But a product feature rarely stops neatly at the API boundary. A new discount changes a server calculation, a preview total, an eligibility message, and a checkout button. What looked like one behavior becomes several tasks across repositories, languages, tests, and release schedules. The teams need a shared understanding of every state, including the states that an API document forgot to name.

Some organizations manage this with two specialist teams and careful coordination. Others ask every developer to work confidently in both stacks. Neither arrangement removes the underlying cost: people still have to understand two execution environments and keep the same product behavior consistent across them. Smaller teams often feel that cost particularly sharply.

The expensive leak is a decision copied across the boundary

Consider a $160 order with a 10% member discount and $12 express delivery. The backend calculates $156. A browser preview must display the same answer. If it reconstructs the discount rules from a customer flag and an item list, it has become another implementation of pricing. A change to the order of operations can produce two believable totals.

The same leak appears when a client infers permission from a role label, invents a workflow status, or guesses whether a refund is allowed. Client validation can improve feedback, but the server still has to enforce the rule. A hidden button cannot authorize an operation. A plausible progress animation cannot establish that a job has finished.

The goal is a clear owner for each decision. Keep pricing, permissions, and state transitions in application services. Pass their results to the view. Keep the view definition in one template. Transport should deliver those results without creating a competing model of the product.

The template is the single source of truth for the view

In Semitexa, a Twig template can remain the authoritative definition of a region whether that region appears in the first HTML response or arrives later. You do not have to maintain a PHP view and a separate JavaScript component that reproduce the same markup, labels, conditions, and empty states.

That statement has a precise scope. The template owns presentation. A PHP service owns business decisions. A repository or external system owns persisted facts. Putting every rule into Twig would recreate the coupling that early PHP applications struggled with. The benefit comes from giving each concern one clear home.

Question	Authoritative place	What the browser receives
What does this order cost?	The PHP quote policy	The calculated amount
How should the quote appear?	One Twig template	HTML, or that published template and its data
When is a slow region ready?	The server operation completing	A deferred delivery frame
Which carousel item is visible?	A small browser interaction	No second pricing or stock policy

Here is part of the actual quote template used by this page. Its inputs are already decided. The template describes the labels and where values appear:

Twig · one view reused by all three quote panels

<h3>{{ quote.deliveryLabel }}</h3>
<dl>
  <div><dt>Member discount</dt><dd>{{ quote.discount }}</dd></div>
  <div><dt>Delivery</dt><dd>{{ quote.shipping }}</dd></div>
  <div><dt>Total</dt><dd>{{ quote.total }}</dd></div>
</dl>

The quote above uses partials/blog-ssr2-quote.html.twig for display and BlogQuotePolicy for its calculation. The Framework demo uses its own shared view and DemoSsrQuotePolicy for the deferred examples. In each case, the browser receives the server's decision rather than recalculating the discount.

Server Side Rendering 2.0: keep the page, improve how it arrives

“Server Side Rendering 2.0” is the architectural idea of this article, rather than a protocol version. Semitexa keeps the request-to-HTML path explicit: a typed payload represents input, a handler coordinates application services, a resource carries the result, and Twig renders the view.

Request                   → typed payload + handler   PHP rules
Decided values            → resource + Twig           First HTML
Slow operation finishes   → deferred SSE delivery     Its region appears

Business decisions remain on the server. A region can arrive later without acquiring a separate frontend implementation.

One slow region no longer has to hold the whole document hostage. A deferred slot reserves space with a skeleton. Semitexa resolves that slot after the shell, then delivers its result. Under the coroutine runtime, independent work can proceed concurrently; a real blocking call or a shared bottleneck still needs attention. Deferring work changes when the page can become useful, not the amount of work a database must do.

The quote below makes the immediate response visible. The linked Framework demos show how deferred regions and an interactive product rail arrive later, without moving the business rule into the browser.

Demo 1: a PHP policy renders the first response

Choose standard or express delivery. This ordinary GET form rerenders the quote on semitexa.com using the same PHP calculation and Twig template. For deferred delivery, open the live Framework demo.

▶ Run the live demo — Member order · $160 subtotal · 10% discount

What each delivery path proves

First response: the page handler calls the PHP policy and Twig renders the view on the server. Deferred HTML: a slot handler can render a view later and send finished HTML over SSE. Deferred template: the server can supply decided values and a reference to a published Twig template for the supported client renderer. Explore those latter paths in the Framework rendering demo.

The third path is especially useful when discussing a single source of truth. Browser rendering does not have to mean a second, independently maintained view. Semitexa's template mode reuses the declared Twig source. It supports a constrained template feature set, so complex server helpers belong in the PHP handler or in HTML mode. Values sent to this mode are visible to the client, just like any other browser payload.

PHP · the calculation used for the quote

// DemoSsrQuotePolicy::quote() — amounts are integer cents.
$subtotalCents = 16000;
$discountCents = intdiv($subtotalCents, 10);
$shippingCents = $delivery === 'express' ? 1200 : 0;
$totalCents = $subtotalCents - $discountCents + $shippingCents;

This is a condensed excerpt of the demo policy; it also formats the amounts and supplies display labels. The page payload accepts the delivery choice, and the deferred handler reads that choice from the page context. In a real checkout, the server would load and authorize the order, calculate against current data, and revalidate on submission. Sharing a template does not freeze a changing business record in time.

Demo 2: a deferred block can bring its own interaction

The Semitexa deferred carousel has a PHP handler for product data and a Twig template for the cards. Once the block arrives, a small client module activates Prev and Next. Try it in the Framework demo: JavaScript selects what is visible, while the product values come from the server.

▶ Open the deferred carousel demo

The fixture products are demonstration data, and the delay is intentional. Reload the Framework demo to watch its skeleton resolve and compare how regions finish independently.

A small declaration describes the delivery contract

PHP · the HTML slot declaration, with its second registration omitted

use Semitexa\Ssr\Attribute\AsSlotResource;
use Semitexa\Ssr\Application\Service\Http\Response\HtmlSlotResponse;

#[AsSlotResource(
    handle: 'demo_blog_ssr2',
    slot: 'ssr2_receipt',
    template: '@project-layouts-semitexa-demo/partials/blog-ssr2-quote.html.twig',
    deferred: true,
    skeletonTemplate: '@project-layouts-semitexa-demo/deferred/blog-ssr2-receipt.skeleton.html.twig',
)]
final class BlogSsr2ReceiptSlot extends HtmlSlotResponse
{
    public function withQuote(array $quote): static
    {
        return $this->with('quote', $quote);
    }
}

In the Framework demo, template delivery registers the same resource with a different slot name and mode: 'template'. Both registrations name the same quote template. A discovered #[AsSlotHandler] supplies the data. That page chooses where each slot appears:

Twig · place a deferred region

<section aria-label="Order quote">
  {{ layout_slot_deferred('ssr2_receipt') }}
</section>

This is useful well beyond a loading animation. A product page can return its title and purchase context while recommendations wait on another service. A dashboard can reveal a quick summary while a slower report resolves. A component can bring a chart module that paints a canvas from server values. Each region has a declared template and lifecycle, instead of a bespoke fetch route plus another hand-written rendering function.

Deferred arrival, periodic refresh, and events are different jobs

Mechanism	Trigger	Good example
Deferred slot	The region finishes preparing	A recommendation service returns
`refreshInterval`	A server refresh interval elapses on a permitted persistent stream	A metrics snapshot checked periodically
Server event	The server emits a change notification	A background task reports completion

A deferred declaration does not automatically subscribe a block to every domain event. Live updates need an explicit publication and subscription path, or an explicitly configured refresh interval. Making that distinction keeps the architecture understandable: “render this later” and “keep this fresh” are related capabilities with different lifecycles.

Demo 3: the server changes, and the browser hears about it

Server rendering can stay live after the initial document has arrived. An SSE connection remains open so the server can send an event when it is produced. The browser does not have to ask every few seconds whether something happened. Delivery still takes processing and network time; “immediate” means pushed after emission, without waiting for the browser's next polling cycle.

The Semitexa SSE showcase lets you sign in, connect, and watch a server notification arrive. A new scheduler.tick follows at each server minute boundary when the debug producer is enabled. Its timestamp is produced on the backend; the visible countdown only predicts the next tick.

▶ Open the live SSE showcase

This optional persistent stream requires sign-in and the demo producer requires debug mode. It is separate from the short deferred delivery shown in the rendering demo.

The event carries the server's answer

PHP · illustrative application event using the installed SSE delivery API

use Semitexa\Ssr\Application\Service\Async\SseAsyncResultDelivery;

// Inside a server-side producer, for an authorized subscriber session.
SseAsyncResultDelivery::deliverRaw($sessionId, [
    'event' => 'report.ready',
    'reportId' => $reportId,
    'sent_at' => gmdate(DATE_ATOM),
]);

Here $sessionId must come from the application's authorized subscriber mapping, and $reportId from completed server work. The snippet illustrates publication; it does not establish subscriptions or authorize a report. The built-in panel uses its own notification and scheduler.tick events so you can inspect a working producer.

For an application, the next step depends on the UI contract. A notification can consume the event fields. A resource response can be rendered on the server and delivered with its HTML through Semitexa's asynchronous result delivery. A subscribed collection can react to a scope invalidation and obtain an updated server projection. In each case, the event announces a fact already decided by the server.

Job finishes                    → persist result + publish   Server event
Application presentation path   → the declared template      Updated view
SSE delivery                    → browser applies result     Visible change

Wire the application's event-to-view path explicitly. The browser can show a completed report without independently deciding when a report counts as complete.

That is the bigger opportunity behind deferred blocks and SSE. A useful page can appear early, a slow block can join it later, and subsequent server activity can reach an already open page. The delivery mechanism evolves while the business rule and the authored view retain clear owners.

AI agents benefit from an architecture with fewer conflicting answers

An AI agent can generate a second price function very quickly. It can also produce a perfectly plausible patch to the wrong one. When a PHP calculation, a TypeScript preview, a server template, and a browser component all describe one checkout, the agent must discover every relationship before changing the behavior safely. Missing one is enough to create drift.

Now give the same task to an agent working on this article's demo: “change the member discount to 15%, and rename the delivery label.” The calculation has one home in DemoSsrQuotePolicy. The shared view has one home in blog-ssr2-quote.html.twig. The first response, deferred HTML, and template delivery can be compared against the same expected result. The task becomes easier to locate, explain, and verify.

This also improves collaboration between people. A designer can work on the Twig markup. A PHP developer can change the policy. A browser specialist can improve carousel behavior or chart accessibility without taking ownership of order calculations. Specialists still matter; the architecture makes their responsibilities easier to join.

Semitexa's typed payloads, handlers, resources, and declared slots expose these relationships to its inspection tools. The Project Graph helps an agent trace dependencies and assess impact before editing. Structural clarity narrows the search; verification still has to prove the outcome.

One template is an architectural advantage, not an automatic correctness guarantee. It removes a duplicated view definition. Keeping business decisions in services removes a duplicated rule implementation. Together, those choices make both human and agent changes easier to reason about.

Use the delivery mode that the region actually needs

Render inexpensive, essential content in the first response. Defer a region when waiting for it would materially delay the page. Keep a stream open when the product needs updates after arrival. A fast label does not improve by becoming a skeleton, and a static paragraph does not need a persistent connection.

For production, make the slow operation bounded, keep placeholders stable, and verify that a failed region can recover without breaking the rest of the page. Check proxy buffering for SSE, decide what reconnect means for your data, and authorize both the initial content and subsequent updates. A cached fragment must respect the user and tenant boundaries of the values it contains.

Test the paths your product promises: first HTML, successful deferred delivery, transport failure, crawler rendering, and JavaScript disabled. This page deliberately keeps the first quote and its form useful without client code. That does not mean an unresolved deferred region magically becomes live without a runtime.

Commerce pages, account screens, forms, content, and operational tools often benefit from this model because the server already owns their important decisions. Rich offline editors, graphics applications, and heavily local interactions can justify a larger client application. Semitexa lets a server-rendered product add live behavior region by region.

The original PHP strength survives: one understandable path from a request to a page. The new capability is that the page can arrive in stages and continue responding to server activity, with one template for its view and one authoritative implementation of its rules.

One view definition. A page that keeps moving.

Explore more deferred regions, inspect streaming SSE, or build your first Semitexa page.

Explore deferred blocks

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Project Graph in Semitexa: Map PHP Dependencies Before You Edit

Taras Hanych — Mon, 28 Sep 2026 10:37:45 +0000

A change to one PHP payload looks small. Which handler consumes it? Which resource does that handler return? Which modules might feel the effect? Project Graph turns those questions into queries against the codebase's structure.

What is a project graph?

A project graph is a map of software entities and the relationships between them. Classes, routes, handlers, services, events, and modules are nodes. Relationships such as “handles this payload,” “implements this interface,” or “depends on this class” are directed edges. Unlike a list of text matches, the graph can answer structural questions: what uses this type, what does it depend on, and what could a change affect?

That is useful when a repository is larger than one person's working memory. A developer can find an entry point before editing; a reviewer can inspect downstream impact; an AI assistant can receive a focused architecture slice rather than a large collection of loosely related files.

Use the graph for structure. Keep using source search when the question is about exact text or a local implementation detail. The graph is most valuable when the question crosses files or modules.

What Semitexa Project Graph actually records

The optional semitexa-project-graph package scans PHP source and Semitexa attributes, extracts structural facts, and stores a directed graph. Its nodes include routes, payloads, handlers, services, events, and execution flows. Its edges capture relationships such as handles, returns, implements, and cross-module dependencies. The stored graph powers several different questions without making each developer reconstruct the architecture from scratch.

The package keeps graph data on its own project_graph database connection, separate from application data. A local SQLite fallback makes the command workflow available without turning the primary database into an architecture index. Build or refresh the graph when you need current answers, then check its state:

bin/semitexa ai:review-graph:generate --json
bin/semitexa ai:review-graph:stats --json

stats reports the indexed files, nodes, edges, and generation time. The counts change as the repository changes; the useful check is that the graph covers the code you are about to reason about. The Project Graph overview demo explains when to reach for it.

A real Project Graph query from Semitexa Demo

Take the original Framework blog index, which now redirects to the canonical articles on semitexa.com. Its BlogIndexPayload still declares the old route, and BlogIndexHandler handles that payload. The following query examines that Demo module relationship:

bin/semitexa ai:review-graph:query \
  --usages='Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --compact --json

The result names BlogIndexHandler and labels the relationship handles. Querying the handler's dependencies also reveals BlogIndexResource as its produced response and TypedHandlerInterface as an implemented contract. These are relationships derived from real code, not a diagram that someone must update by hand.

For a wider view, ai:review-graph:show renders a module slice, while ai:review-graph:module Demo --include-events --include-flows --format=json packages a module overview. The inspection demo shows these commands and the questions each one answers.

Check impact before the edit, then give AI the right context

Finding a direct user is only the first step. ai:review-graph:impact walks downstream relationships and groups affected nodes by distance and module. In the Demo graph used for this example, asking about BlogIndexPayload identifies BlogIndexHandler at distance one:

bin/semitexa ai:review-graph:impact \
  'Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --depth=2 --json

That small result is useful precisely because it is specific. A shared interface or service can produce a much wider radius. Check the result before changing a contract, rather than assuming the file you opened is the whole change surface.

The same package can prepare focused context for a task with ai:review-graph:context. For impact work, --context adds relevant source snippets, and --prompt=review shapes them for a review. This helps an assistant reason from the affected structure instead of starting with an oversized prompt:

bin/semitexa ai:review-graph:impact \
  'Semitexa\Demo\Application\Payload\Request\BlogIndexPayload' \
  --context --prompt=review

The impact and context demo walks through this workflow and the package's watch mode for long editing sessions.

A practical Project Graph workflow

Start with the change you need to make. Name the route, class, event, or module involved.
Ask one structural question. Use query --usages or --dependencies for direct relationships, module for a broader view, or impact for downstream effects.
Check freshness. Read stats and refresh with generate when the stored graph no longer reflects the files relevant to your task. Watch mode can keep it current during a long session.
Verify behavior after the edit. The graph describes structure extracted from code. It cannot prove that every runtime path or test still works.

This is where Project Graph earns its place in Semitexa: the same architecture map serves onboarding, refactoring, code review, and AI-assisted work. It gives each task a narrow, inspectable starting point while keeping the source code and tests as the final authority.

See what your next change can touch.

Start with the Project Graph demos, then run the same commands in a Semitexa project with the package installed.

Explore Project Graph

Project Graph FAQ

Is Semitexa Project Graph required for every application?

No. It is an optional package for repositories where structural queries, impact analysis, and task context pay for themselves.

Is a project graph the same as a text search?

No. Text search finds matching bytes. A graph query follows typed relationships between code entities, such as which handler consumes a payload.

Does Project Graph replace tests?

No. It estimates structural reach from the graph it has built. Run tests and runtime checks to verify actual behavior after changing code.

How does the graph help an AI coding assistant?

It can supply a task-specific view of relevant nodes, edges, and source snippets. That makes a review or implementation prompt more focused and easier to inspect.

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.

Streaming SSE with Semitexa: Live PHP Updates and HTML

Taras Hanych — Mon, 28 Sep 2026 10:37:23 +0000

A page is ready, but its chart is still loading. A background job advances, but the browser has no reason to ask again. Streaming SSE lets the server send each update as it becomes ready over one open HTTP response.

What is streaming SSE?

Streaming SSE means keeping an HTTP response open and sending a sequence of Server-Sent Events instead of waiting to return one complete response. The browser reads the text/event-stream response with EventSource. Each event ends with a blank line; when that frame arrives, JavaScript can act on it while the connection stays open.

Consider a dashboard with a fast heading and a slow chart. A conventional request either makes the whole page wait or asks the browser to fetch the chart separately. A streaming response can deliver the initial page now and the chart when it is rendered. Later events can carry fresh status without a timer that repeatedly polls the server.

event: progress
data: {"job":"report-42","percent":40}

event: progress
data: {"job":"report-42","percent":80}

event: complete
data: {"job":"report-42","url":"/reports/42"}

Those frames illustrate the standard SSE wire format. SSE is the delivery mechanism, not a job queue or a database of missed messages. Your application still decides what to send, who can receive it, and how to recover after a disconnect. If you need the protocol basics first, read our Server-Sent Events guide.

How streaming SSE works in Semitexa

Semitexa has two complementary ways to see the idea in action. The SSE stream demo opens an EventSource connection and shows named events generated by the backend. The deferred blocks demo starts with server-rendered HTML and streams completed regions into their placeholders. Both use the PHP/Swoole runtime; the browser is observing actual server output.

Render a useful page first. The deferred view sends the page shell and skeleton regions without waiting for every slot to finish.
Render slow regions on the server. A slot handler supplies data and a Twig template produces the final HTML. The browser does not have to rebuild that region from JSON.
Deliver results over SSE. The deferred runtime opens its /__semitexa_kiss stream, receives completed blocks, and replaces their placeholders. When the page also has live UI events, the runtime can use the same session and channel instead of opening a separate stream for each feature.

That is the useful Semitexa difference for a server-rendered product: streaming is part of the page delivery model. You can keep your view logic in PHP and Twig, while the transport moves finished HTML to the page as soon as each region is ready. The rendering demos show this alongside other SSR features.

Two distinct use cases: use named SSE events when the browser needs to interpret data such as job progress. Use deferred HTML delivery when the server already owns the UI region. Semitexa supports both; the right choice follows what the client needs to do with an update.

A real Semitexa deferred slot

The chart in Semitexa Demo is declared as a typed slot resource. Here is the relevant part of its actual declaration:

#[AsSlotResource(
    handle: 'demo_deferred_blocks',
    slot: 'deferred_chart_widget',
    template: '@project-layouts-semitexa-demo/deferred/chart-widget.html.twig',
    deferred: true,
    skeletonTemplate: '@project-layouts-semitexa-demo/deferred/chart-widget.skeleton.html.twig',
    clientModules: ['@project-static-semitexa-demo/deferred/chart-widget.js'],
)]
final class DeferredChartWidgetSlot extends HtmlSlotResponse
{
    // The slot handler supplies chart data to this resource.
}

The declaration connects a page handle and slot name to its final Twig template and a skeleton. The page template must place the deferred slot, and its handler must populate the resource. Once wired, the runtime handles late delivery over SSE. clientModules adds behavior for this chart after insertion; it is not required just to receive the HTML.

This matters when a page has several independent slow regions. A product list can be ready while analytics is still computing. Users see the content that is ready, and each later block arrives in the same page instead of forcing an all-or-nothing render. The deferred blocks example lets you inspect the resulting page and shared stream.

Try streaming SSE in the live Semitexa demos

Watch a backend event stream

Open the SSE stream demo, sign in, and connect. The client displays a connection event and listens for named messages such as notification and scheduler.tick. In a debug-enabled demo environment, its countdown follows the next minute boundary and the tick comes from a server-side producer, not the countdown timer. The showcase producer is deliberately disabled when APP_DEBUG is off; ordinary application streams do not depend on it. The page exposes the handler and client JavaScript beside the preview.

Watch server-rendered HTML arrive

Open the deferred blocks demo to see the page shell and skeletons before completed regions arrive. Its stream observer reports the lifecycle of the shared /__semitexa_kiss connection. The runtime owns that connection; the observer does not open another one. A sign-in is required for the persistent stream shown in this demo.

The distinction is visible in the browser: one demo shows event data, and the other shows finished HTML replacing a placeholder. Together they show why SSE streaming is useful beyond a console that prints messages.

What to plan before using streaming SSE in production

Keep frames flowing. Proxy buffering and compression can delay small events. Check the complete path from Swoole to the browser. NGINX documents proxy buffering and the X-Accel-Buffering response header.
Control connection cost. A stream stays open, so budget for concurrent viewers, idle timeouts, heartbeats, and disconnect cleanup. The MDN SSE guide also explains browser connection limits, especially over HTTP/1.x.
Authorize the data. A live stream can outlast the request that opened the page. Check who may subscribe and what each event may reveal. Semitexa's persistent demo stream asks for authentication before it opens.
Design recovery. EventSource normally reconnects after interruption. Reconnection alone does not replay missed updates. Decide whether a view can refresh its current state or needs event IDs, retention, and replay.

Measure the real delivery path. A frame that leaves PHP immediately but sits in a proxy buffer is not a live update for your user.

Build a live PHP page with Semitexa.

Explore the two working streaming flows and use the installation guide to try Semitexa in your own project.

Explore deferred HTML

Streaming SSE FAQ

Is streaming SSE different from Server-Sent Events?

No. It emphasizes the way an SSE response stays open and delivers multiple events over time. Each completed event can update the browser before the response ends.

Does Semitexa require a single-page application for streaming?

No. Deferred slots start from a server-rendered page and deliver completed Twig HTML into it. Client JavaScript handles transport and insertion, while the server continues to own the region's markup.

Can the browser send messages back through the SSE connection?

No. SSE sends data from server to browser. Use a normal HTTP request to start or change work, then use the stream to receive progress or refreshed content.

Will EventSource recover every missed update?

No. It reconnects, but durable delivery needs application-level state, replay, or a fresh snapshot after reconnecting.

This article was first published on the Semitexa blog, where the live demos run next to the text. Semitexa is on GitHub.