PHPackages                             oxphp/stubs - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. oxphp/stubs

ActiveLibrary[Utility & Helpers](/categories/utility)

oxphp/stubs
===========

OxPHP extension stubs for IDE autocompletion and static analysis (PHPStan, Psalm).

v0.7.0(1mo ago)01MITPHPPHP >=8.4

Since Apr 25Pushed 1mo agoCompare

[ Source](https://github.com/oxphp/stub)[ Packagist](https://packagist.org/packages/oxphp/stubs)[ Docs](https://github.com/oxphp/oxphp)[ RSS](/packages/oxphp-stubs/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (6)DependenciesVersions (7)Used By (0)

OxPHP Stubs
===========

[](#oxphp-stubs)

Function stubs for the [OxPHP](https://github.com/oxphp/oxphp) PHP extension (`oxphp_sapi`). Enables IDE autocompletion and static analysis for the `oxphp_*()` functions that the extension exposes at runtime.

This package contains **declarations only** — no executable code. The actual implementations live inside the `oxphp_sapi` extension that ships with the OxPHP server binary.

Install
-------

[](#install)

```
composer require --dev oxphp/stubs
```

Usage
-----

[](#usage)

### PHPStan

[](#phpstan)

If you use [`phpstan/extension-installer`](https://github.com/phpstan/extension-installer), the stubs are registered automatically — nothing else to configure.

Otherwise, add the stubs manually to your `phpstan.neon`:

```
parameters:
    scanFiles:
        - vendor/oxphp/stubs/oxphp.stub.php
```

### Psalm

[](#psalm)

Add the stub file to your `psalm.xml`:

```

```

### PhpStorm / VS Code (Intelephense)

[](#phpstorm--vs-code-intelephense)

Both editors index everything inside `vendor/` automatically, so once the package is installed you get autocompletion and signature hints for free.

Why isn't the stub file autoloaded?
-----------------------------------

[](#why-isnt-the-stub-file-autoloaded)

The `oxphp_sapi` extension declares the same function names at the C level. If this package autoloaded `oxphp.stub.php` at runtime under OxPHP, PHP would fatal with `Cannot redeclare function oxphp_request_id()`. Static analyzers read the file directly without executing it, so they don't hit that problem.

Functions
---------

[](#functions)

### Request & server

[](#request--server)

FunctionPurpose`oxphp_http_request()`Read-only `OxPHP\Http\RequestInterface` for the current request`oxphp_superglobals_enabled()`Whether `$_GET` / `$_POST` / etc. are populated`oxphp_request_id()`Unique 16-hex-char request ID (mirrors `X-Request-ID`)`oxphp_worker_id()`Zero-based PHP ZTS worker index`oxphp_server_info()`Version, worker id, request time, worker-mode flag`oxphp_finish_request()`Flush response, continue work in background`oxphp_is_worker()`True when running under `oxphp_worker()``oxphp_is_streaming()`True for SSE / chunked-transfer requests`oxphp_stream_flush()`Activate streaming mode and flush a chunk`oxphp_worker(callable)`Enter the worker-mode request loop> **Migration (v0.6.0):** `oxphp_request_heartbeat($time)` was removed. Replace each call with `set_time_limit($seconds)` — both reset the per-request execution timer to N seconds from now.

### Cooperative scheduling

[](#cooperative-scheduling)

FunctionPurpose`oxphp_sleep(float)`Cooperative fiber sleep in seconds (falls back to `usleep`)`oxphp_usleep(int)`Cooperative fiber sleep in microseconds### Async tasks

[](#async-tasks)

FunctionPurpose`oxphp_async(Closure, ...$args)`Dispatch a closure to the async worker pool`oxphp_async_await(int, ?float)`Block until a single promise resolves`oxphp_async_await_all(int[], ?float)`Wait for every promise, return all results`oxphp_async_await_race(int[], ?float)`First promise to settle wins (fulfil **or** reject) — `Promise.race``oxphp_async_await_any(int[], ?float)`First promise to **fulfil** wins; all-reject throws `AggregateAsyncException` — `Promise.any`### Decorators

[](#decorators)

FunctionPurpose`oxphp_register_decorator(string)`Register an `#[Attribute]` class as a decorator### APM (OpenTelemetry tracing)

[](#apm-opentelemetry-tracing)

FunctionPurpose`oxphp_apm_trace(string, callable, array)`Run callback inside an auto-closed child span`oxphp_apm_start(string, array)`Open a manual child span (pair with `oxphp_apm_end()`)`oxphp_apm_end(int)`Close a manually opened span`oxphp_apm_attribute(string, mixed, ?int)`Add an attribute to the current (or given) span`oxphp_apm_event(string, array, ?int)`Add a named timestamp event to a span`oxphp_apm_error(Throwable, ?int)`Record an exception event and mark the span as error`oxphp_apm_status(int, ?string, ?int)`Set explicit span status (`OXPHP_APM_OK` / `OXPHP_APM_ERROR`)`oxphp_apm_trace_id()`Current 32-hex W3C trace ID`oxphp_apm_span_id()`Current 16-hex active span ID`oxphp_apm_header()`Build a W3C `traceparent` header value for outbound HTTPConstants: `OXPHP_APM_OK`, `OXPHP_APM_ERROR`. Plus the `#[OxPHP\Apm\Trace]` attribute, auto-registered when APM is enabled, that wraps the annotated function/method in a span.

### Profiler (`OxPHP\Profile`)

[](#profiler-oxphpprofile)

FunctionPurpose`OxPHP\Profile\is_active()`Whether profiling is actively capturing spans`OxPHP\Profile\start()`Enable profiling for the rest of the current request`OxPHP\Profile\stop()`Stop further span capture`OxPHP\Profile\pause()` / `resume()`Soft pause / resume around hot sections`OxPHP\Profile\mark(string, array)`Attach a named marker event to the topmost open span`OxPHP\Profile\metric(string, float)`Append a numeric `metric.` attribute to the current spanProfiler attributes: `#[Profile]`, `#[Exclude]`, `#[Sample(rate)]`, `#[Tag(key, value)]` (repeatable), `#[Mark(label?)]`, `#[SlowThreshold(ms)]`, `#[MemoryThreshold(kb)]`.

### Shared primitives (`OxPHP\Shared`)

[](#shared-primitives-oxphpshared)

Process-wide concurrent primitives visible from every PHP worker thread.

ClassPurpose`Counter`Lock-free `Relaxed` atomic signed 64-bit counter`Atomic`Generic atomic signed 64-bit integer with explicit `Ordering` (load/store/swap/CAS/fetch arithmetic & bitwise)`Flag`Atomic boolean with explicit `Ordering` (load/store/swap/CAS)`Once`Run-once container with cross-worker init; `Reset` / `Poison` failure modes`Mutex`Cross-thread mutex — `withLock()` / `tryWithLock()` / `withLockTimeout()``Channel`Bounded MPMC `Countable` queue; result-typed `recv*` / `send*` (no hot-path exceptions)`Map`Concurrent `int|string → mixed` key-value store with CAS and cycle detection`Pool`Bounded object pool — `acquire()` / `tryAcquire()` / `acquireTimeout()`, RAII `Handle`, `Stats``Registry`Name-keyed process-global get-or-create for every `Shared\*` type`Ordering` is a backing-`int` enum (`Relaxed`, `Acquire`, `Release`, `AcqRel`, `SeqCst`) consumed by `Atomic` / `Flag`; every method defaults to `SeqCst`.

The bounded-wait convention across `Shared\*`: a bare method (`acquire`, `withLock`, `recv`) waits forever, a `try*` method is non-blocking, and a `*Timeout(int $ms)` method waits a bounded number of milliseconds (`$ms` must be `> 0`).

Exception hierarchy under `OxPHP\Shared\`: `SharedException` ← `StaleHandleException`, `TypeException` ← `CycleException`, plus `CapacityException`, `ValueTooLargeException`, `ClosedException`, `PoisonedException` (deprecated), `UninitializedException`, `InvalidOrderingException`, `CorruptedMutexException`. Bounded-wait failures extend `OxPHP\Async\AsyncException` instead — `OperationTimeoutException`, `ContentionException`, `DeadlockException` — so one `catch (AsyncException)` sweeps both Shared and Async timeouts.

Supporting sub-namespaces: `Shared\Once\{Status, FailureMode}` enums; `Shared\Map\KeyCursor` (lazy `getMany()` iterator); `Shared\Channel\{RecvStatus, SendStatus, RecvResult, SendResult}`; `Shared\Pool\{Handle, Stats}`.

All Shared types implement the `OxPHP\Shared\Shareable` marker interface so they can be nested inside `Map` / `Channel` without serialisation.

### Server runtime (`OxPHP\Server`)

[](#server-runtime-oxphpserver)

Per-thread handle for the OxPHP worker runtime, returned by `Worker::current()`.

MethodPurpose`Worker::current()`Per-thread `Worker` singleton`Worker::isWorkerMode()`Whether this thread runs in worker mode (mirrors `oxphp_is_worker()`)`id()`Worker thread index (`0..N-1`)`startTime()`Float Unix timestamp when the thread was spawned`requestCount()`Requests this thread has started (1-based)`memoryUsage()`Current Zend allocator usage in bytes`rss()`Process RSS in bytes`maxMemoryBytes()`Configured worker memory cap in bytes (0 = none)`scheduleExit()`Mark this worker for graceful exit after the current request`isExitScheduled()`Whether a graceful exit is pending for this worker`exitReason()`Pending-exit reason (`scheduled` / `max_memory` / `error`) or `null``serve(callable)`Enter the worker request-dispatch loop`Worker::serve()` throws `OxPHP\Server\Exception\InvalidServeContextException` when called outside worker mode.

### Object API

[](#object-api)

The stub also declares the namespaced surface that the extension exposes at runtime:

- `OxPHP\Http\{RequestInterface, SessionInterface, UploadedFileInterface, AttributesInterface}` and their final implementations (`Request`, `Session`, `UploadedFile`, `Attributes`).
- `OxPHP\Http\Exception\{NoActiveRequestException, AsyncContextException, WorkerIdleException}` — thrown by `oxphp_http_request()` outside a live request context.
- `OxPHP\Async\{AsyncException, TimeoutException, AggregateAsyncException, BorrowException, BorrowedProxy}` — thrown by the `oxphp_async_*()` family. `TimeoutException` exposes `getPartialErrors()` / `getCancelledPromiseIds()` (populated by `oxphp_async_await_any()`); `AggregateAsyncException` carries every rejection when all promises fail. `BorrowedProxy` is the opaque stand-in injected when a `use`-captured value is still borrowed by the source thread; every access throws `BorrowException`.
- `OxPHP\Decorator\{AttributeInterface, Context, RejectedException, StackOverflowException}` — implement `AttributeInterface` and register with `oxphp_register_decorator()` to intercept calls. `RejectedException` is thrown when a Rust-native decorator rejects the call; `StackOverflowException` when nested decorated calls exceed the decorator context stack depth (256 levels).
- `OxPHP\Apm\Trace` — automatic span attribute (auto-registered when APM is enabled).
- `OxPHP\Profile\*` — profiler functions and attributes (see above).
- `OxPHP\Shared\*` — process-wide concurrent primitives (see above).
- `OxPHP\Server\Worker` and `OxPHP\Server\Exception\InvalidServeContextException` — per-thread worker runtime handle (see above).

See [`oxphp.stub.php`](oxphp.stub.php) for full PHPDoc with parameter types, return types, and usage examples.

License
-------

[](#license)

MIT — see [LICENSE](LICENSE). The OxPHP server itself is licensed under AGPL-3.0-or-later; the stubs are kept permissive so they can be safely added to any project as a dev dependency.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance90

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

6

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4af090c8589bcc76cd8aed3847b3f20740298c9f26060a03e3e4f5a34aaf84cc?d=identicon)[Diolektor](/maintainers/Diolektor)

---

Top Contributors

[![diolektor](https://avatars.githubusercontent.com/u/425040?v=4)](https://github.com/diolektor "diolektor (7 commits)")

---

Tags

composer-packagedeveloper-toolside-autocompleteoxphpphp-extensionphpstanpsalmstatic-analysisstubsPHPStanautocompleteidestatic analysisstubsphp-extensionpsalmoxphp

### Embed Badge

![Health badge](/badges/oxphp-stubs/health.svg)

```
[![Health](https://phpackages.com/badges/oxphp-stubs/health.svg)](https://phpackages.com/packages/oxphp-stubs)
```

###  Alternatives

[phalcon/ide-stubs

The most complete Phalcon Framework IDE stubs library which enables autocompletion in modern IDEs.

1703.3M136](/packages/phalcon-ide-stubs)[php-stubs/wordpress-stubs

WordPress function and class declaration stubs for static analysis.

20116.0M436](/packages/php-stubs-wordpress-stubs)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)