Laravel Web3 Laravel Package

Getting Started

Install and configure

composer require renoki-co/laravel-web3
php artisan vendor:publish --tag=web3

The published config/web3.php is the first place to look — it defines the node connection(s). Point it at an Ethereum JSON-RPC endpoint via env so you can swap Infura, Alchemy, QuickNode, or a local Ganache/Hardhat node per environment:

WEB3_HTTP_HOST=https://mainnet.infura.io/v3/your-key

First use case

The quickest sanity check is a read-only call through the facade:

use RenokiCo\LaravelWeb3\Facades\Web3;

$blockNumber = Web3::getEth()->blockNumber()->val(); // latest block height
$balance = Web3::getEth()->getBalance('0xabc...');   // wei as hex string

If that returns a height, your provider, network, and credentials are wired up. If it throws, the problem is almost always the endpoint URL, a missing project ID, or a firewall blocking outbound JSON-RPC — not the package itself.

Implementation Patterns

Facade for one-off reads, injected client for anything structured. The facade resolves a singleton of the underlying web3p/web3.php client. For controllers and jobs, prefer constructor-injecting the client (or a small repository class that wraps it) so you can swap it in tests:

class BalanceService
{
    public function __construct(private \Web3\Web3 $web3) {}

    public function balanceOf(string $address): string
    {
        $this->web3->getEth()->getBalance($address)->val(); // string of wei
    }
}

Read contracts through a prepared ABI. Keep ABI JSON files under resources/abi/ and load them once, not per call. The typical pattern is a Contract object built from the ABI plus a deployed address, then invoking methods by name. This is the workhorse for ERC-20 balances, allowances, NFT ownership, and view-only data — the majority of day-to-day Web3 work.

Treat writes as a job, never a request. Sending a transaction means nonce management, gas pricing, signing, and confirmation waiting — all too slow and too failure-prone for an HTTP request. Push them into a queued job, store the returned tx hash in a model, and have a separate poller (queue or scheduled command) update status by calling getTransactionReceipt until the block is mined. Emit a domain event when confirmed so the rest of your app stays chain-agnostic.

Separate signer from node. Most hosted providers won't expose the personal namespace, so the reliable pattern is to sign locally (a keystore/private key held in a secret store) and broadcast raw signed transactions. Keep private keys out of .env in production — use a secrets manager — and never log method arguments that contain them.

Cache aggressively on chain reads. Block heights, balances, and view calls are natural cache targets. A 10–15 second TTL on balances and a "cache until next block" strategy via block number keys will keep you well under provider rate limits without meaningfully stale data.

Multi-chain in one app. Configure distinct connections (mainnet, a testnet) and resolve per-connection clients. Keep the network ID alongside any persisted tx records so you never confuse a hash from one chain with another.

Gotchas and Tips

This package is archived (last release July 2022). It still works as a thin wrapper over web3p/web3.php, but treat it as frozen. Budget for either pinning the underlying library version or migrating to calling web3p/web3.php directly — the wrapper adds little beyond a facade and config, so the migration is small. Do not expect fixes for PHP 8.2+ deprecations upstream.

Wei values will overflow. PHP integers are 64-bit; large ETH/ERC-20 balances exceed PHP_INT_MAX. Always treat balances, gas prices, and amounts as strings (or bignum objects) end-to-end. Never intval() a wei value — this is the single most common correctness bug in Web3 PHP code.

Hosted providers differ in supported namespaces. Infura/Alchemy commonly disable personal, and some restrict eth_newFilter on HTTP. If a method works on Ganache but 403s on your provider, check the provider's supported-method matrix before assuming the package is broken.

Debug by dumping the raw eth call result object. The client returns result wrappers with ->val() and ->error; inspecting the error message directly is faster than catching a generic exception. Wrap calls in try/catch around \Exception and log the provider's error string.

HTTP transport is synchronous and has no built-in retry. Add retries with exponential backoff around transient 429/5xx responses from providers — a naive loop will hammer rate limits. Set explicit timeouts on your HTTP client so a hung node doesn't tie up queue workers.

WebSocket/filter subscriptions are unreliable in the PHP client. newFilter + getFilterChanges on HTTP requires your poller to run frequently enough to beat provider filter expiry (often ~5 minutes). For confirmation tracking, polling getTransactionReceipt by hash is more robust than filters.

Facade testing needs an explicit swap. Web3::shouldReceive(...) only works if the facade accessor is registered; if you inject the client instead, bind a fake in the container. Prefer the injected-client pattern precisely so this stays clean.

Config caching bites in production. php artisan config:cache freezes the node URL — after rotating a provider key, you must re-cache or the app keeps calling the old endpoint. Keep provider credentials in env and out of the cached config where possible.

ABI loading is your extension point. The package won't parse Solidity for you; wrap a small AbiLoader that reads JSON, validates it, and memoizes decoded contract definitions. This is where you attach per-contract helpers (e.g., Token::balanceOf, NFT::ownerOf) and keep controllers free of raw hex and ABI arrays.