Laravel Web3 Laravel Package

Technical Evaluation

Architecture fit

• renoki-co/laravel-web3 is a thin Laravel integration layer over web3p/web3.php: a service provider that binds a configured Web3 client into the container, a facade, and a publishable config file holding the node endpoint. There is essentially no business logic, no persistence, and no queue integration — it is glue, not a framework.
• That is a good architectural fit for Laravel's idioms (DI, facades, config caching, .env-driven endpoints) and a poor fit as a long-term dependency boundary. Because the wrapper is shallow, the real risk surface sits in the transitive dependency tree (web3p/web3.php, Keccak/hash primitives, big-integer math, secp256k1 signing helpers, Guzzle), not in the package itself.
• Ethereum interaction is synchronous JSON-RPC. That maps cleanly to Laravel's HTTP/Guzzle stack for reads, but signing and transaction broadcast should not live on the request path of a user-facing PHP-FPM process.

Integration feasibility

• Mechanical integration is trivial: composer require, publish config, set WEB3_DEFAULT_ACCOUNT / node URL, inject the facade. Days, not weeks, for a read-only proof of concept against a testnet.
• The blocking issue is version drift. Last release 2022-07-20 and archived: expect illuminate/* constraints capped around Laravel 8/9 and PHP 7.4–8.1. On Laravel 10/11 or PHP 8.2/8.3 you will likely need --ignore-platform-reqs, a constraint patch, or an internal fork. Verify the actual constraint matrix before committing to an estimate.
• Functional ceiling is whatever web3p/web3.php exposes: eth, net, personal, contract deploy/call, raw transaction signing. There are no typed DTOs, no retry/backoff, no idempotency keys, no event indexing, no revert-reason decoding, and no EIP-1559 gas strategy beyond what you write yourself.

Technical risk

• Archived status is the dominant risk. No security patches, no PHP/Laravel compatibility work, no CVE response, no upstream issue triage. Any fork becomes your code the moment you touch it.
• Key material handling. If the package is used for signing, private keys transit PHP process memory and application logs are a realistic leak vector. This deserves a threat model, not a code review.
• Dormant upstream. web3p/web3.php itself has low maintenance velocity; archiving the wrapper usually signals the author has moved on rather than that the underlying client is healthy.
• Silent breakage. Chain and node-client upgrades (EIP changes, gas semantics, RPC response shapes, provider deprecations) will not be reflected in a frozen dependency.

Key questions

1. Read-only (balances, calls, event reads) or does this path sign and broadcast transactions? The answers diverge sharply on risk and governance.
2. Which chains and L2s? The wrapper assumes a single JSON-RPC endpoint; multi-chain means multiple named connections and config, which is not what the package models.
3. What is the custody model — app-held keys, KMS/HSM, or an external signer? If KMS/HSM is required, this package's signing surface is the wrong layer.
4. Which Laravel and PHP versions are in the target stack, and what is the supported-versions policy?
5. Do we need event indexing / historical log queries? If yes, this package is not the tool; an indexer is.
6. Is there appetite to own a fork with CI, or is the preference to depend only on maintained code?

Integration Approach

Stack fit

• Best fit: Laravel 8/9, PHP 7.4–8.1, read-heavy workloads against a managed node provider (Infura/Alchemy/self-hosted), no key custody in the app.
• Poor fit: Laravel 10+, PHP 8.2+, multi-chain, signing with production keys, or any workflow requiring exactly-once transaction semantics.

Migration path

• Option A — Adopt with containment. Use the package, but never reference the facade directly in domain code. Define a narrow Web3Gateway interface in the app (getBalance, call, sendRawTransaction, getReceipt) and implement it with this package. This preserves the fast start while making the dependency swappable in one file.
• Option B — Reimplement the glue (recommended default). The wrapper is a provider + config + facade binding. Reproducing it against web3p/web3.php directly is a small, well-understood task and removes one archived artifact from the critical path while keeping identical functionality and API shape. This is the lowest-regret path.
• Option C — Bypass entirely for reads. If only reads are needed, plain JSON-RPC over Laravel's HTTP client eliminates the crypto dependency tree and the archived package at once. Add typed request/response classes and a retry policy.
• If Option A is mandated, pin exact versions, commit the lockfile, run composer audit in CI, and schedule the fork as planned work rather than reactive work.

Compatibility checklist

• PHP extensions: gmp or bcmath, mbstring, openssl; confirm presence in every runtime image including queue workers and CI.
• Config caching (php artisan config:cache) — endpoints and keys must resolve from env at boot, not at call time.
• Node endpoint secrets must not be logged; Guzzle request logging will capture URLs containing provider API keys.

Sequencing

1. Week 0 — Spike. Testnet PoC against a managed node; record latency percentiles, error rates, and the actual composer constraint matrix. Decision gate: does it install cleanly on the target Laravel/PHP?
2. Week 1 — Interface. Land Web3Gateway + config + observability hooks. No domain code touches the package.
3. Week 2 — Read paths. Balances, contract calls, receipts, behind cache and retry policy. Ship behind a feature flag.
4. Week 3+ — Write paths (gated). Only after custody review. Signing isolated in a queue worker, never in the web tier.
5. Parallel — Exit plan. Fork or Option B/C migration scoped and estimated before the first production write.

Operational Impact

Maintenance

• Treat as internally owned from day one. Budget ongoing cost for: a maintained fork or replacement, PHP/Laravel upgrade work the upstream will never do, and dependency CVE monitoring (composer audit, Dependabot, SCA in CI).
• Track the EOL clock explicitly: PHP 8.1 and Laravel 9 both reach end of security support on published dates; this package cannot follow the stack past them without a fork.
• Add a "no new call sites" lint or architecture test so the facade does not spread while the exit plan is pending.

Support

• There is no upstream support channel. Escalation ends at an internal SME. Identify that person and make it a named role, not an assumption.
• Runbooks required before production writes: node provider outage, rate-limit (429) storm, stuck/nonce-collided transaction, chain reorg invalidating a confirmed read, and key-rotation procedure.

Scaling

• PHP's request-per-call model means throughput is bounded by node provider rate limits and per-call latency, not by application CPU. Plan for batching (eth_getBalance fan-out, JSON-RPC batch arrays), caching of quasi-static data (eth_chainId, eth_gasPrice with short TTL), and queue-based write submission.
• Reads scale horizontally behind a cache. Writes scale only if signing is centralized — otherwise concurrent workers race on nonce allocation. Nonce management must be a single-writer concern.
• Keep signing in a dedicated worker pool with a bounded concurrency of one per account.

Failure modes

• Node provider 429/5xx/timeout — surfaces as opaque Guzzle exceptions; without a retry policy, user-facing errors.
• Malformed or unexpected RPC responses after a provider or node-client upgrade; a frozen dependency will not adapt.
• Nonce collisions and stuck transactions under concurrent load; no built-in replacement/cancel logic.
• Gas mispricing (legacy vs EIP-1559) leading to dropped transactions.
• Reorg-induced inconsistency: a "confirmed" read later becomes false; requires a confirmation-depth policy.
• Irreversible loss from key mishandling or a signing-path bug — the one failure mode with no rollback.
• Silent rot: the package installs today and fails in eighteen months at a stack upgrade, with no upstream to fix it.

Ramp-up

• Read-only usage: roughly one engineer-day to first working call, plus a day for the abstraction layer and observability. Familiarity with Laravel is sufficient.
• Signing usage: several engineer-weeks including custody design, security review, and failure-mode runbooks. The team needs Ethereum fundamentals (nonces, gas, confirmations, reorgs, ABI encoding) — Laravel experience does not transfer here.
• Organizational ramp-up: someone must own the dependency's fate. Assign that ownership before the first commit, because "archived and unowned" is the failure mode that actually bites.