Frequently Asked Questions

general

How does Nexphant compare to Laravel Octane or RoadRunner?

Laravel Octane and RoadRunner run a PHP application within a persistent worker process, but they rely on an external Go server (RoadRunner) or a PHP extension (Swoole/Swoole-based engines) to manage the event loop. Nexphant is a managed runtime engine built directly on PHP native fibers and event loop integrations, requiring no compiled custom C/Go extensions to orchestrate task lifecycles, resource cleanups, or cancellation propagation.

Does Nexphant require Swoole or FrankenPHP?

No. Nexphant does not require Swoole, RoadRunner, or FrankenPHP. It runs on standard PHP 8.1+ using native fibers and event loop drivers. For optimal event loop performance, standard PHP extensions like ext-ev or ext-event are recommended but not required.

Is Nexphant production-ready?

Yes. Nexphant is benchmarked at 84k req/s (static JSON, tuned, 1000 VUs) on a consumer-grade machine. See Benchmarks.

What PHP version is required?

PHP 8.1 minimum (native Fibers). PHP 8.2+ recommended for readonly classes and improved GC.

---

memory & safety

Do I need to worry about memory leaks?

In traditional PHP, no — each request dies and memory is freed. In persistent PHP, yes. Nexphant minimises this through its deterministic ownership model: sockets, DB transactions, and buffers are attached to a context owner (request, job, fiber). When the owner completes, resources are released automatically.

For long-running background jobs that allocate heavily, you can run the cycle collector manually:

gc_collect_cycles();

How do I detect a leak?

Use the runtime doctor endpoint:

$app->runtime('/api'); // exposes /api/metrics

Or query it directly:

curl http://localhost:8080/api/metrics

Watch owner_count, resource_count, and memory usage over time. A steadily growing count indicates a scope is not being closed.

What happens if a fiber throws an uncaught exception?

The exception is caught by the event loop. The request is terminated with a 500 response, the owner scope is closed (resources released), and the worker continues handling other requests. The worker does not crash.

What happens when a worker crashes?

The supervisor restarts it automatically. Enable the supervisor:

$app->supervisor(true);

---

concurrency & fibers

How many concurrent requests can Nexphant handle?

Each request runs in its own fiber. Fibers are lightweight (~few KB each). A single worker can hold thousands of suspended fibers. Throughput depends on I/O wait time, CPU, and worker count.

Do fibers run in parallel?

No. PHP fibers are cooperative, not parallel. Only one fiber runs at a time per process. Workers run in separate OS processes — workers: 4 gives you 4 parallel processes.

Is it safe to use static properties?

Only for process-lifetime singletons (service containers, config, caches). Never for request-scoped state. Static data persists across requests within a worker. Use Context for per-request data.

// Unsafe — leaks between requests
class Auth {
    public static ?User $current = null;
}

// Safe — scoped to current request context
Context::set('current_user', $user);

---

compatibility

Can I use my existing Composer packages?

Yes. Standard PHP libraries that do not store state globally (or can reset their state) run correctly on Nexphant. Database clients, logger formatters, HTTP clients, and utility packages are fully compatible.

What about packages that use exit() or die()?

exit() in a persistent worker terminates the entire process and disrupts all active fibers. Replace exit() with exceptions:

// Before
exit(1);

// After
throw new \RuntimeException('Fatal error');

Some third-party packages call exit() internally — wrap them in a subprocess or use alternatives.

Can I use Nexphant with Laravel?

Yes, via nexphant/laravel-adapter. The adapter bootstraps the Laravel kernel once and handles requests through persistent workers.

Does Nexphant support WebSockets?

Yes. Register a WebSocket route:

$app->ws('/chat',
    onMessage: fn ($conn, $msg) => $conn->send("echo: $msg"),
    onOpen:    fn ($conn) => null,
    onClose:   fn ($conn) => null,
);

---

database

What databases are supported?

MySQL, PostgreSQL, and SQLite via the nexphant/database package. Connection pools are managed automatically.

What happens when a database connection times out?

The pool discards the dead connection and opens a new one. Active fibers waiting for a connection are not affected — they receive a fresh connection when one becomes available.

Can I use raw PDO?

Yes, but manage it through ConnectionPool so connections are properly recycled and not leaked between requests.

---

deployment

How many workers should I run?

Start with workers = CPU cores. For I/O-heavy workloads (lots of DB queries), try CPU cores × 2. Monitor pressure metrics and adjust.

Can I run multiple Nexphant nodes behind a load balancer?

Yes. Each node is stateless from the load balancer's perspective. Ensure session or cache state is stored externally (Redis, DB) if needed across nodes.

How do I zero-downtime deploy?

1. Deploy new code to a second node or use a blue/green setup.
2. Send SIGTERM to the old process — it drains in-flight requests then exits.
3. Start the new process.

Systemd with Restart=always handles this automatically when you run systemctl restart nexphant-app.

Next Steps

• Migration Guide
• Production Tuning
• Benchmarks