PHPackages                             glueful/runiva - 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. [DevOps & Deployment](/categories/devops)
4. /
5. glueful/runiva

ActiveGlueful-extension[DevOps & Deployment](/categories/devops)

glueful/runiva
==============

Runiva: Server runtime integration for Glueful (RoadRunner, Swoole, FrankenPHP)

v0.9.1(2w ago)10MITPHPPHP ^8.3

Since Oct 15Pushed 2w agoCompare

[ Source](https://github.com/glueful/runiva)[ Packagist](https://packagist.org/packages/glueful/runiva)[ Docs](https://github.com/glueful/runiva)[ RSS](/packages/glueful-runiva/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (13)Versions (13)Used By (0)

Runiva (Server Runtime) for Glueful
===================================

[](#runiva-server-runtime-for-glueful)

Overview
--------

[](#overview)

Runiva integrates alternative server runtimes with the Glueful Framework — RoadRunner (default), (Open)Swoole, and FrankenPHP. It provides a unified command, environment‑driven configuration, and a PSR‑7 bridge to route HTTP requests through Glueful’s Application and Router.

Features
--------

[](#features)

- ✅ RoadRunner worker and config (rr.yaml)
- ✅ PSR‑7 bridge auto‑detection (Nyholm + Symfony bridge)
- ✅ Single console entrypoint: `runiva:serve`
- ✅ Config‑driven via `.env` + merged config
- ✅ Composer discovery via `extra.glueful.provider`
- ⚙️ Stubs for Swoole and FrankenPHP server scripts

Requirements
------------

[](#requirements)

- PHP 8.3+
- Glueful Framework 1.22.0+
- Optional (RoadRunner mode):
    - `spiral/roadrunner` (binary management + base worker)
    - `spiral/roadrunner-http` (PSR‑7 HTTP worker)
    - `nyholm/psr7`, `symfony/psr-http-message-bridge` (PSR‑7 <-> HttpFoundation)

Optional (Swoole/OpenSwoole mode):

- PHP extensions: `ext-swoole` or `ext-openswoole` (installed via PECL/package manager)

Installation
------------

[](#installation)

```
composer require glueful/runiva

# Enable it — installing does not auto-load an extension; this adds the provider to
# config/extensions.php's `enabled` list and recompiles the cache.
php glueful extensions:enable runiva
```

In production, manage the `enabled` list in config and run `php glueful extensions:cache` in your deploy step.

RoadRunner (recommended for HTTP)

```
composer require spiral/roadrunner spiral/roadrunner-http nyholm/psr7 symfony/psr-http-message-bridge
```

Verify Installation
-------------------

[](#verify-installation)

```
php glueful extensions:list
php glueful extensions:info runiva
php glueful extensions:diagnose
```

Getting Started
---------------

[](#getting-started)

Configuration via `.env` (all optional; defaults provided):

- `RUNIVA_RUNTIME=roadrunner|swoole|frankenphp`
- `RUNIVA_BINARY=rr` (RoadRunner binary or absolute path)
- `RUNIVA_CONFIG=vendor/glueful/runiva/rr.yaml`
- `RUNIVA_WORKERS=2`
- `RUNIVA_ADDRESS=:8080`

Runiva merges defaults from `config/runiva.php` within the package. App‑level `.env` values override these. You can also create `config/runiva.php` in your app to hard‑set values.

Usage
-----

[](#usage)

Start the configured runtime:

```
php glueful runiva:serve
```

Validate configuration and environment without starting:

```
php glueful runiva:serve --check
```

Force a specific runtime:

```
php glueful runiva:serve --runtime=roadrunner
php glueful runiva:serve --runtime=swoole
```

RoadRunner uses the included `rr.yaml` by default:

```
server:
  command: "php vendor/glueful/runiva/bin/worker.php"
http:
  address: ":8080"
  pool:
    num_workers: 2
```

### RoadRunner + PSR‑7 Bridge

[](#roadrunner--psr7-bridge)

With `spiral/roadrunner-http`, `nyholm/psr7`, and `symfony/psr-http-message-bridge` installed, the worker will:

- Receive PSR‑7 requests from RoadRunner
- Convert to Symfony HttpFoundation requests
- Dispatch through Glueful Application/Router
- Convert Symfony responses back to PSR‑7 and respond

RR worker lifecycle (simplified):

- Bootstrap Glueful once (Framework::create()->boot()).
- Loop: waitRequest() → convert PSR‑7 → handle → convert response → respond.
- On SIGTERM/SIGINT/SIGQUIT: exit loop and allow RR to stop workers gracefully.

watch plugin (dev hot‑reload) in rr.yaml:

```
plugins:
  watch:
    patterns: ["**.php", "rr.yaml"]
    ignore: ["vendor/**", "storage/**"]
    jobs: ["http"]
```

### Swoole / FrankenPHP

[](#swoole--frankenphp)

Swoole/OpenSwoole:

- Install the extension: `ext-swoole` or `ext-openswoole` must be enabled in PHP.
- Start the server:

```
php glueful runiva:serve --runtime=swoole
```

FrankenPHP:

- Ensure the `frankenphp` binary is installed and on PATH, or set `FRANKENPHP_BINARY` to its full path.
- Start the server:

```
php glueful runiva:serve --runtime=frankenphp
```

Notes:

- The launcher generates a minimal Caddyfile and runs `frankenphp run --config `.
- It sets `APP_ENV` based on your environment; adjust `RUNIVA_ADDRESS` to change the listen address (default `:8080`).
- For production, prefer a full Caddy configuration with TLS, timeouts, and headers tuned for your deployment.

#### Production Caddyfile (example)

[](#production-caddyfile-example)

```
{
  # Global server options
  servers {
    timeouts {
      read_header 10s
      read_body   30s
      write       30s
      idle        2m
    }
    trusted_proxies private_ranges
  }
}

example.com {
  # ACME/Let’s Encrypt or email for zero‑config certificates
  tls you@example.com

  # Serve static assets efficiently
  encode zstd gzip

  # Path to your app’s public directory
  root * /var/www/public

  # Security headers (adjust CSP for your frontend needs)
  header {
    Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    X-Frame-Options "SAMEORIGIN"
    X-Content-Type-Options "nosniff"
    Referrer-Policy "no-referrer"
    X-XSS-Protection "0"
    Content-Security-Policy "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'"
  }

  # Long‑cache immutable assets
  @static {
    file
    path *.css *.js *.png *.jpg *.jpeg *.svg *.ico *.woff *.woff2 *.ttf *.map
  }
  handle @static {
    header Cache-Control "public, max-age=31536000, immutable"
    file_server
  }

  # PHP application served by FrankenPHP
  handle {
    php_server {
      # Optional tuning
      # worker 4
      env APP_ENV=production
      env APP_DEBUG=0
    }
  }

  # Structured access logs
  log {
    output stdout
    format json
  }
}
```

Adjust `example.com`, `root`, and header policies to your needs. For multi‑app setups, define multiple site blocks or use `handle_path` to mount sub‑apps.

Hot‑Reload
----------

[](#hotreload)

- RoadRunner: enable the `watch` plugin in `rr.yaml` or run with `rr --watch` during development to auto‑reload workers on file changes.
- Swoole/OpenSwoole: send `SIGUSR1` to the master PID to reload workers gracefully (`kill -USR1 `), or use a file‑watcher script to trigger reloads.
- FrankenPHP: restart the `frankenphp run` process (or reload Caddy) after code changes.

### Graceful Shutdown

[](#graceful-shutdown)

- RoadRunner: Runiva’s worker handles `SIGTERM/SIGINT` and exits loops cleanly.
- Swoole/OpenSwoole: hooks registered for `shutdown` and `workerStop` events for orderly teardown.
- FrankenPHP: process termination is handled by the launcher/Caddy; no extra hooks required.

Troubleshooting
---------------

[](#troubleshooting)

- Changes to `.env` and configs require a RoadRunner restart (hot workers persist state).
- If the worker logs that PSR‑7 bridge is unavailable, install:
    - `spiral/roadrunner spiral/roadrunner-http nyholm/psr7 symfony/psr-http-message-bridge`
- Ensure `rr` is installed and on PATH, or set `RUNIVA_BINARY` to an absolute path.

Health & Readiness
----------------------

[](#health--readiness)

Glueful exposes server‑agnostic health endpoints you can rely on in any runtime:

- `GET /healthz` — liveness check (200 OK when the process is up)
- `GET /ready` — readiness check (dependencies ready; secured via IP allowlist middleware by default)
- `GET /health` — full health suite root with sub‑routes (database, cache, middleware, response‑api, queue)

Examples (enable/adjust per your env/security):

- `GET /health/database` — DB connectivity and migrations status
- `GET /health/cache` — cache connectivity and basic operations
- `GET /health/detailed` — extended metrics (auth required)
- `GET /health/middleware` — middleware pipeline health (auth required)
- `GET /health/response-api` — response API health (auth required)
- `GET /health/queue` — queue stats and worker activity

---

Runiva is designed to be minimal and composable. Start with RoadRunner and PSR‑7 for full HTTP performance, then layer in Swoole or FrankenPHP as needed.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance86

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

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 ~24 days

Recently: every ~33 days

Total

11

Last Release

20d ago

PHP version history (2 changes)v0.1.0PHP ^8.2

v0.6.0PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/95650726?v=4)[msowah](/maintainers/msowah)[@msowah](https://github.com/msowah)

---

Top Contributors

[![MichaelSowah](https://avatars.githubusercontent.com/u/24699905?v=4)](https://github.com/MichaelSowah "MichaelSowah (27 commits)")

---

Tags

serverruntimeswooleroadrunnerfrankenphp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/glueful-runiva/health.svg)

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

###  Alternatives

[laravel/octane

Supercharge your Laravel application's performance.

4.0k26.6M223](/packages/laravel-octane)[moonshine/moonshine

Laravel administration panel

1.3k253.1k81](/packages/moonshine-moonshine)[sentry/sentry-laravel

Laravel SDK for Sentry (https://sentry.io)

1.3k127.1M203](/packages/sentry-sentry-laravel)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.1k17.8k](/packages/prestashop-prestashop)

PHPackages © 2026

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