Download the PHP package gndlf/xrpl_php without Composer

PHP XRPL

PHP SDK / Client Library to interact with the XRP Ledger and the Xahau Network. It offers all the functionality available in the JavaScript and Java Versions emphasizing robustness and code readability for those interested in looking under the hood and getting into the nitty-gritty of XRPL development.

Features

1. XRP Ledger / rippled version 3.4.0 compatible
2. Managing & creating keys and wallets
3. Submitting transactions to the XRP Ledger
4. Sending requests to observe the ledger
5. Creating and signing transactions (e.g. Payments) to modify the ledger state
6. Parsing ledger data into more convenient formats
7. Every transaction and ledger entry flag as a named constant

Installation

This library is installable via Composer:

composer require hardcastle/xrpl_php

Requirements

This library requires PHP 8.2 or later and two PHP extensions:

• bcmath — used directly for the ledger's fixed point arithmetic.
• gmp — required by simplito/elliptic-php, which does the secp256k1 signing. Composer will refuse to install without it.

Examples

The "Quickstart" Examples

These examples reproduce the functionality from the JavaScript quickstart examples:

How-to Examples

These examples show how to use key features:

All of these run against the Testnet and fund their own wallets from the faucet.

Core Examples

These examples can be used to explore XRPL core functionality:

Agent Skill

This repository includes an Agent Skill that teaches AI coding agents (Claude Code, Codex CLI, Cursor and others) how to use this SDK: the real API instead of a guess from xrpl.js, every transaction model and flag, the request class for every API method, and the errors to expect. See skills/ for installation; with the skills CLI it is one command, with Claude Code's plugin manager two:

Try it yourself

Issuing an account_objects request

Making a payment

Signing yourself and submitting the blob works just as well, and is what the files in examples/ do:

The objects behind the client

JsonRpcClient is a facade. Behind each of its operations sits a class that can also be used on its own:

The functions in the Hardcastle\XRPL_PHP\Sugar namespace do the same and keep working, but they are deprecated as of 2.2.0 and delegate to these classes.

Xahau support

The library ships the Xahau transaction types alongside the XRP Ledger ones, but the two networks have drifted apart: Xahau kept its URIToken types on the ordinals 45–49 and moved everything the XRP Ledger added afterwards further up. MPTokenIssuanceCreate, for instance, is 54 on the XRP Ledger and 63 on Xahau. A single set of definitions cannot be correct for both networks, and this library resolves the overlap in favour of the XRP Ledger.

Works on Xahau:

• All classic transaction types — Payment, AccountSet, TrustSet, OfferCreate/OfferCancel, Escrow*, Check*, PaymentChannel*, NFToken*, AMM*, Clawback, TicketCreate, SignerListSet, DepositPreauth, AccountDelete, SetRegularKey. These carry the same ordinal on both networks.
• The Xahau-specific types — SetHook, Invoke, Import, ClaimReward, GenesisMint, UNLReport, URIToken*, TicketCancel.

Does not work on Xahau yet:

• Every type the XRP Ledger added from ordinal 41 onwards: XChain*, DID*, Oracle*, MPToken*, Credential*, PermissionedDomain*, NFTokenModify. These encode with the XRP Ledger ordinal, which means a different transaction type on Xahau — without an error. Do not submit them to Xahau.
• Decoding is ambiguous for the five shared ordinals: a Xahau URITokenMint decodes as XChainAddClaimAttestation, and the Xahau Blob field decodes as DIDDocument. The bytes are correct, only the names are read through the XRP Ledger definitions.
• hooksDefinitions.json predates the current Xahau release and is missing Remit, SetRemarks, Cron and CronSet.

Using your own definitions

Since 2.1.0 the codec works against definitions handed in from outside, so a package for another network can supply its own definitions.json instead of the bundled one. Every entry point takes an optional Definitions instance and falls back to the XRP Ledger when it is omitted:

A node serves its own definitions, so they can be fetched rather than vendored:

The definitions travel through the whole encode and decode, including nested objects and arrays. They do not touch the shared default instance, so a process can talk to both networks at once.

Replacing what the client works with

The definitions decide how a transaction is encoded, but not everything a network does differently. Xahau prices a transaction individually, because hooks may fire, so the XRP Ledger's fee formula produces too low a fee there.

Since 2.3.0 the client exposes the objects it works with, and a subclass can substitute one:

The replacement is used wherever that object is reached, including submitAndWait(), which autofills through the Submitter rather than through the client. The same works for getSubmitter(), getAccountReader(), getOrderbookReader(), getFeeCalculator() and getFaucet().

A dedicated Xahau package building on this is planned; the Xahau types will then move out of this library.

Development

Running the project via Docker

1. Tell the container which user to run as, so the files it writes belong to you. The values differ between Linux and macOS, so they come from .env:

2. Start the project and open a shell:

3. In the container shell, install the composer dependencies:

The image is built from docker/. Xdebug is preconfigured to reach the host on port 9090 via host.docker.internal, which works on Linux as well because the compose file maps it to the host gateway. For anything else that is specific to your machine, add a docker-compose.override.yml; it is gitignored.

Keeping the definitions current

definitions.json is a verbatim snapshot of a rippled node's server_definitions, never a copy of another SDK's file. To refresh it:

Then php skills/build.php regenerates the agent skill's references, and the parity test tells you what else the new version touches. In Claude Code the /xrpl-php-sync-definitions skill walks through the whole procedure.

Working with an agent

.agents/skills/ holds the skills for working on this repository, in the directory Codex, Cursor, Gemini CLI, Copilot and most other agents read; .claude/skills/ symlinks to it for Claude Code. They are: xrpl-php-sync-definitions (see above), xrpl-php-release (prepares a release branch, pull request and release notes; merging and tagging stay with the maintainer), xrpl-php-review (audits a branch against the XRPL protocol checklist and the repository's conventions, findings only) and xrpl-standards, every XLS specification as a reference file with an index by transaction and ledger object name. The specifications are a verbatim copy from XRPLF/XRPL-Standards, committed so that nothing has to be fetched at install time; a weekly workflow opens a pull request when upstream changes. To check by hand:

None of this is in the Composer package.

Running the tests

The unit tests, which CI runs on every push:

The integration tests talk to the public Testnet and its faucet. CI runs them after a push to main; locally:

You can perform static code analysis with psalm with the following command: