Download the PHP package sandermuller/solana-php-sdk without Composer

solana-php-sdk

A PHP SDK for the Solana blockchain. Read accounts, sign and submit transactions, watch the chain over WebSockets, and call any Anchor program — all from PHP.

Status: open source under MIT. Works on PHP 8.3 / 8.4 with Laravel 11 / 12 / 13.

What you get

Who this is for

• PHP devs new to Solana. Start with the 5-minute quickstart — you'll send a real on-chain transfer.
• Laravel apps. The package auto-registers a service provider; resolve Connection straight from the container.
• Standalone PHP scripts. A one-liner bootstrap (Bootstrap::createContainer) wires up the same container outside Laravel.

Install

The package self-registers SanderMuller\SolanaPhpSdk\ServiceProvider via Laravel's package discovery. Standalone PHP doesn't need anything extra — see "Outside Laravel" below.

Requirements: PHP 8.3+ with ext-sodium enabled (every mainstream PHP distro ships it). Composer pulls in paragonie/sodium_compat as a polyfill backup.

Building a Laravel app? Install the sister wrapper instead — it adds the Solana facade, ConfirmTransactionJob, env-driven config, and 7 artisan commands (balance, account, transaction, fees, health, …) on top of this SDK:

Repo: https://github.com/SanderMuller/laravel-solana-sdk. You get this SDK as a transitive dep — no need to require both.

5-minute quickstart

We'll go from zero to a signed-and-broadcast SOL transfer on devnet.

1. Generate (or load) a keypair

Store the secret bytes somewhere safe if you want to reuse this wallet:

2. Get some devnet SOL

3. Check your balance

4. Send SOL to someone

Click the URL — your transaction is on-chain.

Sign from a KMS / HSM / hardware wallet

For hosts that cannot expose secret bytes to PHP (KMS-backed keys, Ledger devices, remote signing services), implement Contracts\MessageSigner:

For the in-process case, wrap a Keypair in Signing\InMemoryMessageSigner to get the same interface.

Sketch: HashiCorp Vault Transit

Sketch: Ledger hardware wallet

The Ledger Solana app expects a base58-derivation-path-prefixed APDU. Wrap any USB/HID transport (e.g. via a sidecar process bridged over stdio) and implement signMessage() as a single INS_SIGN_MESSAGE APDU round-trip.

Sanitize-safe builder

Most transaction failures across Solana SDKs hit the same opaque error: "Transaction failed to sanitize accounts offsets correctly". The fluent TransactionBuilder catches the causes locally so you never see that message:

build() throws UnsanitizedTransactionException if the fee payer is missing, the blockhash is missing, an instruction marks an account isSigner with no matching keypair, or two instructions disagree on whether the same account is a signer. Every detected reason is surfaced at once on $exception->reasons.

One-shot send-and-confirm

Most apps want both steps in one call, with blockhash-expiry built in:

The helper fetches getLatestBlockhash, signs, sends, and polls getSignatureStatuses until the commitment is reached or the blockhash expires — no manual retry loop.

Core concepts (the 90-second glossary)

Common recipes

Read an account

Legacy $connection->getAccountInfo(...) still returns the raw RPC array.

Read multiple accounts at once

List the SPL Token accounts owned by a wallet

Paginate a large program scan

For programs with too many accounts to fetch in a single getProgramAccounts round-trip, partition the scan by account dataSize. The generator emits a ProgramAccount per row across one RPC call per bucket:

Scan a program for accounts matching a filter

GpaFilter::memcmp() accepts a PublicKey, Buffer, or raw base58 string — the most common drift point across Solana SDKs (offset / encoding swap) is locked in the builder.

Look up recent signatures for an address

Watch a signature land (WebSocket)

Survive socket drops

Long-running consumers (indexers, queue workers) can opt in to transparent reconnect — the client respawns the socket, replays every active subscription, and resumes yielding notifications without the caller noticing the gap:

Backoff is exponential with full jitter (baseDelayMs * 2^attempt, randomly shrunk to avoid thundering-herd on a cluster outage). Subscription ids change across the reconnect — the new id ships inside each notification's subscription field, so don't key per-id state on the integer if you enable this.

Add a memo to a transaction

The Memo program writes raw UTF-8 bytes into the transaction log so off-chain indexers can correlate transactions with application data. signers is optional — list any public keys that must be verified as transaction signers (Memo v2 behaviour).

Pay the priority fee the network is currently asking

Samples getRecentPrioritizationFees and returns the requested percentile in micro-lamports per compute unit. Returns 0 when the network is idle — no fee is necessary in that regime.

Token-2022 mint extensions

Memo-transfer (require a Memo instruction in every incoming transfer):

Send a Token-2022 transfer

Token-2022 inherits every core discriminator from legacy SPL Token — the program-id is the only difference. The ATA address differs between the two programs even for the same (owner, mint) pair, so derive it through $program->getAssociatedTokenAddressSync() rather than reusing a legacy-Token ATA.

Build a v0 transaction with an Address Lookup Table

Use the resulting lookupTableAddress as an AddressLookupTableAccount when compiling a MessageV0.

Verify an Ed25519 signature

Call an Anchor program from its IDL

Supported IDL types: every primitive in the Anchor 0.30 spec (u8..u64, i8..i64, f32/f64, bool, string, bytes, pubkey) plus vec<T>, array<T, N>, and option<T>. User-defined struct types raise a clear validation error so you pre-encode them.

Using with Laravel

This SDK works inside a Laravel app out of the box via auto-discovery — Connection resolves straight from the container. For the full Laravel-flavoured experience (facade, queue job, env-driven config, artisan commands), install the wrapper instead:

Repo: https://github.com/SanderMuller/laravel-solana-sdk. The wrapper requires this SDK as a transitive dep — install just the wrapper, not both.

Outside Laravel

The SDK doesn't require a Laravel app. Use the bootstrap helper:

The config file lives at config/solana-php-sdk.php once you publish it (php artisan vendor:publish --tag=solana-php-sdk-config inside Laravel, or copy the package's default) and defines the network and SPL Token program id.

Reference — every typed RPC method on Connection

Reference — PubSub subscriptions

SolanaPubSubClient covers every documented WebSocket method: accountSubscribe, signatureSubscribe, slotSubscribe, rootSubscribe, logsSubscribe, programSubscribe, voteSubscribe, blockSubscribe. Use the generic subscribe(method, params) for anything else.

The constructor accepts a clientFactory: Closure(): WebSocket\Client so tests can inject a scripted-reply double instead of opening a real socket.

Troubleshooting

Account not found when reading a fresh wallet. Solana doesn't allocate storage until the first deposit. Airdrop / transfer something in first, or catch AccountNotFoundException.

Transaction simulation failed: Blockhash not found. The blockhash you attached has expired (~60–90 s). Call getLatestBlockhash() again and rebuild the transaction.

Transaction signature verification failed. You signed with the wrong keypair, or modified the transaction after signing. Re-sign after every mutation. Confirm feePayer matches your first signer.

SolanaPubSubClient blocks forever in listen(). Pass maxEvents: to stop after N events, or wrap the loop in a deadline and call close().

PublicKey::verify() returning false even with the right key. Solana signatures are over the raw message bytes, not a hash. Pass the exact bytes you signed, with no JSON-encoding or string interpolation in between.

Airdrop ignored. Devnet rate-limits per IP and per recipient. Wait a few minutes or use a faucet website.

Examples

Runnable scripts under examples/:

• examples/quickstart-transfer.php — airdrop, balance, transfer, confirm.
• examples/anchor-call.php — load an IDL, build an instruction, simulate.
• examples/pubsub-watch-signature.php — subscribe and block until a tx finalises.

Each script is standalone — composer install then php examples/quickstart-transfer.php.

Comparison to other Solana clients

Compared to the canonical Solana SDKs across all languages

This SDK is built against the recurring pain points operators hit in @solana/web3.js, @solana/kit, solana-py / solders, solana-go, and solana-sdk / anchor-client. The matrix below is the short version; see the rationale beneath it.

What we built against

• Blockhash expiry is typed, not opaque. sendAndConfirmTransaction tracks lastValidBlockHeight and trips BlockhashExpiredException instead of swallowing the failure or silently re-signing — the #1 cross-SDK footgun in web3.js issues #1987 / #2361.
• Structured errors instead of raw RPC strings. sendTransaction / simulateTransaction failures raise a SendTransactionError carrying a decoded TransactionError (InstructionError(2, Custom(6000)), BlockhashNotFound, InsufficientFundsForRent { account_index }, …), full program logs, and unitsConsumed.
• Pluggable RPC transports. Add a Helius primary + Triton backup + public fallback in a config block — the SDK round-robins or fails over on transient errors. Per-endpoint exponential-backoff retry decorator included.
• Auto compute-budget + priority-fee on build. TransactionBuilder::withAutoComputeBudget() simulates, reads unitsConsumed, scales by a safety buffer, and injects both setComputeUnitLimit + setComputeUnitPrice before signing. No other SDK ships this by default — every other ecosystem leaves it as a Helius / Quicknode blog-post recipe.
• Laravel-native async story (in sandermuller/laravel-solana-sdk). ConfirmTransactionJob::dispatch($sig, $lvbh) hands the long-tail confirmation phase to a queue worker, then fires TransactionConfirmed / TransactionExpired events (defined here in the SDK). Inherits retries + DLQ from your queue backend — Kit's async-iterator API cannot match this on PHP-FPM.
• InMemoryRpcStub + Pest expectations. InMemoryRpcStub::script([...]) feeds a deterministic RPC reply queue. Pest macros (toBeConfirmed, toHaveCustomCode, toBeInstructionError) ship in this SDK — usable from any test runner. The wrapper adds Solana::fake() as a Laravel-flavoured one-liner over the same stub. Other SDKs stand up a local validator just to write a unit test.
• Sanitize-safe builder. Catches duplicate-account flag conflicts, missing signers, and orphaned isSigner flags locally before the RPC round-trip — so you never see "Transaction failed to sanitize accounts offsets correctly", the single most-reported cross-SDK error.
• PDA + ATA one-liners. Pda::find($programId, $seeds) and Ata::derive($owner, $mint) (with a Token2022Program::TOKEN_PROGRAM_ID argument or the Ata::derive2022() shortcut). Most SDKs hardcode the legacy SPL Token program in the ATA helper.

Roadmap

Tracked separately as GitHub issues; the high-level next steps are:

• In-process test validator (litesvm-style) — drive transactions against a deterministic SVM execution layer without an RPC round-trip. Out of scope for this release; the Rust litesvm crate is the reference. Track issues tagged harness.
• Token-2022 advanced extensions — confidential transfer (ZK proofs), transfer hook (CPI to a host program), metadata pointer. Initialize-only versions of transfer-fee, mint-close-authority, permanent-delegate, non-transferable, immutable-owner, memo-transfer already ship.
• Concrete KMS adapters — AWS KMS, GCP KMS, HashiCorp Vault, Ledger. The MessageSigner interface is stable; hosts implement against their preferred backend (see README sketches above).

Where to ask for help

• Solana JSON-RPC reference: https://solana.com/docs/rpc
• Anchor / IDL docs: https://www.anchor-lang.com/docs/basics/idl
• Faucet (devnet SOL): https://faucet.solana.com
• Explorer: https://explorer.solana.com
• Issues / PRs: GitHub

Development

Contributing

Issues and PRs welcome. Please run composer qa before opening a PR.

License

MIT — see LICENSE.