Download the PHP package alexhackney/lara-nimble without Composer

Laravel Nimble Package

A comprehensive Laravel package for the Nimble Streamer native management API. Inspect live streams and sessions, manage RTMP republishing, DVR archives, publish control, the data cache and more with a clean, expressive Laravel interface.

Developed by Alex Hackney

[]() []()

Every service maps 1:1 to endpoints documented in the Nimble native API reference — nothing is invented, and every request/response shape is covered by tests.

Features

• ✅ Live Streams: Inspect currently publishing streams (bandwidth, resolution, codecs, publisher)
• ✅ RTMP Republishing: Create, list, delete and monitor republish rules (YouTube, Facebook, Twitch, ...)
• ✅ Restream Reconciler: sync() converges the server onto your desired rule set — built for Nimble's non-persistent API rules
• ✅ First-class Testing: Nimble::fake() with request recording and assertions
• ✅ Session Management: List and terminate active client sessions
• ✅ DVR Control: Archive status, MP4 export, reload and cleanup
• ✅ Publish Control: List active publishers and deny (disconnect) them
• ✅ Server Management: Status, config reload, SSL certificate reload, WMSPanel sync, playlist status
• ✅ Data Cache: Resolve cache keys and evict cached items
• ✅ Protocol Insights: RTMP settings, MPEG-TS status/settings, SRT/RIST stats, NDI list
• ✅ Icecast: Read stream info and inject metadata
• ✅ SCTE-35: Insert cue-out/cue-in/time_signal ad markers (Nimble Advertizer)
• ✅ Type Safety: Strict types, readonly DTOs, PHP 8.3+
• ✅ Laravel Integration: Service provider, facade, config, artisan commands, events, validation rules

Requirements

• PHP 8.3, 8.4 or 8.5
• Laravel 12 or 13
• Nimble Streamer with the management API enabled

Installation

Step 1: Install via Composer

Step 2: Publish Configuration

This will create a config/nimble.php file in your Laravel application.

Step 3: Configure Environment Variables

Minimal Configuration - Add only what you need to your .env file:

That's it! The package uses sensible defaults for everything else.

Optional Overrides - Only add these if you need to change the defaults:

Step 4: Enable Nimble API

Ensure your Nimble server has the API enabled. Edit /etc/nimble/nimble.conf:

Restart Nimble after configuration changes:

Usage

Live Streams

Nimble's native API exposes currently publishing streams via /manage/live_streams_status. A stream that is not live simply does not appear.

Restream Management (RTMP Republishing)

Restreaming uses Nimble's native RTMP republishing API (/manage/rtmp/republish).

Reconciling rules with sync()

Because API-created rules disappear on Nimble reloads, the typical pattern is a reconciler: declare the rules you want, and let sync() converge the server. Rules are compared by fingerprint (every field except id); missing rules are created, unwanted or duplicate rules deleted, matching rules left untouched. WMSPanel-defined rules are never affected because the native API cannot see them.

Run it on deploy, on a schedule, or after Nimble::server()->reloadConfig() — it is idempotent. RestreamRuleCreated / RestreamRuleDeleted events fire for every change, so you get an audit trail for free.

Notes from the Nimble API docs:

• src_stream is optional in the raw API, but omitting it republishes every stream in the source application, so RestreamDto refuses to build a create payload without it.
• list() only returns rules created through the native API — rules defined in WMSPanel do not appear.
• Rules created through the native API are not persisted across a Nimble config reload or restart; recreate them as needed.

Session Management

DVR Management

Publish Control

Requires publish control to be enabled in Nimble's RTMP settings.

Server Management

Data Cache

Nimble's data cache holds responses for remote VOD and similar content, addressed by keys derived from origin URLs.

Protocol Status & Settings

These endpoints return structures defined by Nimble or the respective protocol specs, so they are exposed as raw arrays.

Icecast

SCTE-35 Ad Markers

Requires the Nimble Advertizer feature.

Using in Controllers

Using in Jobs/Queues

Configuration

The package is designed for minimal configuration. Only two settings are required in your .env:

All other settings have sensible defaults that work for most use cases. The config/nimble.php file shows all available options with their defaults:

You only need to override these in .env if the defaults don't work for your setup.

Optional Response Caching

Dashboards polling stream or server status every second shouldn't hammer the Nimble API. When enabled, streams()->list() (and therefore byApp()/find()/exists()) and server()->status() are served from a short-TTL cache:

Disabled by default. Note that StreamExistsRule also sees cached data while this is on.

Testing Your Application

Nimble::fake() swaps the manager for a test double. The real services and DTO parsing still run — only the HTTP layer is faked — so your tests exercise exactly the code paths production uses.

Unstubbed endpoints respond {"status": "Ok"}, so happy paths work with no stubs at all. Available assertions: assertSent(), assertNotSent(), assertSentCount(), assertNothingSent(), assertRestreamCreated(), assertRestreamDeleted(); callbacks receive (string $method, string $endpoint, array $data, array $query). Facades also support standard Mockery mocking (Nimble::shouldReceive()) if you prefer stubbing at the service level.

Integration Tests (against a real server)

The package ships an opt-in suite that runs read-only checks plus a full republish-rule lifecycle against a live Nimble instance:

Without NIMBLE_TEST_HOST the suite skips itself, so composer test stays hermetic. Use this once against staging to prove your Nimble version matches the package's expectations.

Artisan Commands

Check Server Status

Displays connections, out rate and RAM/file cache usage.

List Live Streams

Lists currently live streams with protocol, resolution, bandwidth and publisher.

Clear Data Cache

Health Check

Performs a connectivity and configuration check of your Nimble server.

Validation Rules

The package includes custom validation rules for Laravel forms:

Laravel Events

Available Events

• AlexHackney\LaraNimble\Events\RestreamRuleCreated — fired after restream()->create() (and per create in sync()), carrying the created RestreamDto
• AlexHackney\LaraNimble\Events\RestreamRuleDeleted — fired after a successful restream()->delete() (and per delete in sync())
• AlexHackney\LaraNimble\Events\SessionTerminated — fired per session id after a successful sessions()->terminate()
• AlexHackney\LaraNimble\Events\CacheCleared — fired after cache()->delete() removes items (not on dry runs)

Listening to Events

Register in EventServiceProvider:

Testing

Unit tests cover every service against mocked HTTP with request path, method and body assertions, plus all DTOs and the HTTP client; feature tests cover the Laravel integration.

Troubleshooting

Connection Issues

If you're getting connection errors:

1. Verify Nimble is running: sudo systemctl status nimble
2. Check firewall allows port 8082
3. Verify NIMBLE_HOST and NIMBLE_PORT in .env
4. Test API manually: curl http://your-server:8082/manage/server_status

Authentication Errors

If you're getting 401/403 errors:

1. Verify management_token in /etc/nimble/nimble.conf matches your NIMBLE_TOKEN
2. If not using authentication, remove NIMBLE_TOKEN from .env
3. Restart Nimble after config changes

SSL Verification Issues

For development/testing with self-signed certificates:

Note: Never disable SSL verification in production!

API Documentation

For detailed Nimble API documentation, visit:

• Nimble API Reference
• Nimble Configuration Guide

Development

Project Structure

Contributing

We welcome contributions! To contribute code:

1. Fork the repository and create a feature branch
2. Follow PSR-12 coding standards (composer format)
3. Write tests for new features
4. Ensure all tests pass: composer test
5. Run static analysis: composer analyse
6. Open a Pull Request

When adding endpoints, verify them against the Nimble API reference first — this package only wraps documented endpoints.

Support

For issues and questions:

• GitHub Issues: Report an issue
• Source Code: View on GitHub

Security

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

Changelog

See CHANGELOG.md for version history and release notes.

License

The MIT License (MIT). See LICENSE for details.

Repository: https://github.com/alexhackney/lara-nimble