Routeros Api Php Laravel Package

Technical Evaluation

Architecture fit evilfreelancer/routeros-api-php is a framework-agnostic Composer library, not a Laravel package. It speaks the MikroTik RouterOS binary API (sentence-based protocol on TCP 8728 / API-SSL 8729) and ships two client generations: a legacy RouterOS\Client and a newer query-builder client. Architecturally it belongs at the infrastructure edge of the Laravel app — behind a RouterOsGateway interface (or repository), consumed by jobs/services, with the library itself never leaking into domain code. Fit is strong only where MikroTik is a first-class part of the estate (WISP/ISP provisioning, PPPoE/hotspot subscriber management, CPE fleet config, bandwidth scripting). Where RouterOS is peripheral, the cost of owning an unabstracted socket client outweighs the benefit.

Integration feasibility Composer-installable, PSR-4, PSR-3 logger injection, array-based config. It has no Laravel service provider, no auto-discovery, no publishable config, no facade — all glue is ours. That is a one-off 1–3 day build (provider + config + lazy singleton connection + health check), not a blocker. The 1.7.0 content is three targeted fixes and no API surface change, so integration effort is unchanged from 1.6.0.

Technical risk

• Blocking I/O: the client holds a synchronous TCP socket. Any call on the request path ties up a PHP-FPM worker for the duration of the RouterOS round trip; a hung router hangs the worker. This is the dominant risk and is exactly what the PHP 8.4 stream-timeout fix (PR #140, issue #131) addresses — but timeout correctness must be validated by us, not assumed.
• Empty/nested script responses: PR #139 fixes parseResponse throwing on empty payloads for nested :execute-style scripts. This was a real production failure class for anyone driving RouterOS scripting rather than plain commands; the fix materially improves reliability of the scripting path.
• Windows compatibility + dev dependency bump (PR #142): relevant to developer laptops and CI runners, not to Linux production. Low risk, but it means the dev-dependency tree moved — lockfile diff should be reviewed.
• Platform drift: PHP 8.4 stream semantics are the canary. The project is responsive but small; the three fixes arrived via two first-time contributors, which cuts both ways (healthy funnel, variable review depth).
• Security posture: no security fixes in 1.7.0. The library will happily send credentials in plaintext over 8728 and will not verify certificates unless configured — that is a config-discipline risk we own.
• Release hygiene: semver-minor bump for a pure fix set is conservative and fine; no breaking changes, no deprecations.

Key questions

1. Does the PHP 8.4 timeout fix cover both the legacy and modern clients, and does it apply on connect as well as read?
2. Is the empty-parseResponse fix covered by a regression test, and does it distinguish "legitimately empty" from "truncated frame"?
3. Which RouterOS versions did the maintainers test against — v6.4x, v7.x, or both? Our fleet mix matters.
4. Does the Windows fix touch TLS/CA path resolution? If so, our Windows devs' local SSL setup may change behaviour.
5. What is the project's stated support window for PHP and RouterOS majors, and is there a maintainer bus factor we should hedge?
6. Do we have a containerised RouterOS (CHR) instance in CI to validate against, or are we testing against production hardware?

Integration Approach

Stack fit Target PHP 8.2–8.4 with Laravel 10/11/12. Bind the client as a lazily-constructed singleton in a small RouterOsServiceProvider, with a config/routeros.php covering host, port, username, password, TLS toggle, connect/read timeouts, and logging channel. Expose only narrow, typed methods on our gateway (provisionSubscriber, setQueue, runScript, fetchActiveSessions) so the library is swappable. Never resolve the client in a controller — dispatch a job.

Migration path

• Phase 0 — spike (2–3 days): install 1.7.0, connect to a CHR instance, exercise plain commands, nested scripts, and a forced timeout.
• Phase 1 — read-only (1 week): wire fetchActiveSessions/interface stats into a dashboard behind a flag. No writes. Validates auth, TLS, and timeout behaviour under real latency.
• Phase 2 — writes (2–3 weeks): move existing SSH/CLI or cron-script automation onto gateway methods, one operation at a time, each with a rollback path to the old script.
• Phase 3 — decommission: retire legacy shell scripts and stored credentials from .env.

Compatibility Pin ^1.7.0 and commit the lockfile. Verify against the RouterOS firmware versions actually deployed, not just latest — the API differs meaningfully between v6.4x and v7. Confirm PHP 8.4 locally and in CI; the timeout fix is the whole point of this bump, so it must be exercised. Re-run the Windows developer setup (per PR #142) before anyone rebases onto 1.7.0.

Sequencing Bump dependency → review dev-dependency lockfile diff → run gateway contract tests against CHR → confirm the three fix areas explicitly (timeout, empty nested script, Windows dev) → staging with production-shaped latency → production behind a feature flag → delete the 1.6.x fallback after one stable week.

Operational Impact

Maintenance Low upstream churn (three PRs in this cycle), but we own the Laravel wrapper, the config schema, and the gateway interface — that is our permanent surface, not theirs. Budget roughly one day per quarter for dependency bumps plus a re-test against the current RouterOS release. Track upstream issues #131 and #136 as closed so we can drop any local workarounds.

Support The dominant support ticket will remain "router unreachable / request hung." 1.7.0 improves the library's timeout behaviour, but first-line triage still needs: is the socket reachable, are credentials valid and in an API-permitted group, is the router's API service enabled on the expected port. Publish a runbook. Because two of the three fixes come from first-time contributors, treat 1.7.0 as a normal-risk dependency bump rather than a trust signal — regression-test rather than assume.

Scaling Each command occupies one TCP connection, and RouterOS serialises work per connection; concurrency means multiple connections, not multiplexing. For fleets in the hundreds-to-thousands, run provisioning through dedicated queue workers with per-router rate limiting and backoff, cap worker pool size so a router outage cannot exhaust the queue, and keep read-polling on a schedule rather than per-request. Throughput is bounded by the router, not by Laravel — size expectations accordingly.

Failure modes

• Socket hang with no timeout → worker starvation (mitigated by PR #140; verify our timeout config is actually applied).
• Empty response on nested script execution → exception or silent no-op (mitigated by PR #139; confirm it degrades gracefully rather than masking a truncated frame).
• Auth failure after a RouterOS upgrade or a default-group change → whole feature dark, loud but not silent.
• Plaintext credentials on 8728 → policy breach; mandate API-SSL with certificate validation outside isolated management VLANs.
• Windows dev environment divergence (paths, certs) → "works on my machine" before a release (addressed by PR #142).
• No connection pooling → retry storms during partial router outages; cap retries and add jitter.

Ramp-up Expect 2–4 engineer-days for a mid-level Laravel developer to be productive, plus a hard dependency on someone with RouterOS CLI literacy (groups, services, /export, scripting). Two docs are non-negotiable before Phase 2: the gateway interface reference and an incident runbook for hung/unreachable routers. The library's API is simple; the operational knowledge is the actual learning curve.

Recommendation Adopt 1.7.0. It is a low-risk, non-breaking bump that closes three observed field issues — the PHP 8.4 timeout and nested-script empty-response fixes are directly relevant to production stability, and the Windows fix removes a developer-experience divergence. Treat it as the baseline assessment for this dependency: no Laravel-native integration exists, so the wrapper is ours to own and document.