Get Started Using PHP Library

This tutorial walks you through the basics of building an XRP Ledger-connected application using XRPL_PHP, a PHP library built to interact with the XRP Ledger.

This tutorial is intended for beginners and should take no longer than 30 minutes to complete.

Learning Goals

In this tutorial, you'll learn:

The basic building blocks of XRP Ledger-based applications.
How to connect to the XRP Ledger using XRPL_PHP.
How to get an account on the Testnet using XRPL_PHP.
How to use the XRPL_PHP library to look up information about an account on the XRP Ledger.
How to put these steps together to create a simple application.

Requirements

XRPL_PHP requires PHP 8.1 and the PHP extension GMP.
The PHP extension BCMATH is recommended for increased performance.

Installation

XRPL_PHP can be installed via Composer:

composer require hardcastle/xrpl_php

Start Building

When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP to your account, integrating with the decentralized exchange, or issuing tokens. This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them.

Here are the basic steps you'll need to cover for almost any XRP Ledger project:

Connect to the XRP Ledger.
Get an account.
Query the XRP Ledger.

1. Connect to the XRP Ledger

To make queries and submit transactions, you need to connect to the XRP Ledger. To do this with XRPL_PHP, you can use the JsonRpcClient:

<?php

// Use the Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Imports 
use XRPL_PHP\Client\JsonRpcClient;

// Create a Client using the Testnet
$client = new JsonRpcClient("https://s.altnet.rippletest.net:51234");

Note that PHP has no native support for WebSockets, so the Client does not establish a permanent connection.

Connect to the production XRP Ledger

The sample code in the previous section shows you how to connect to the Testnet, which is one of the available parallel networks. When you're ready to integrate with the production XRP Ledger, you'll need to connect to the Mainnet. You can do that in two ways:

By installing the core server (rippled) and running a node yourself. The core server connects to the Mainnet by default, but you can change the configuration to use Testnet or Devnet. There are good reasons to run your own core server. If you run your own server, you can connect to it like so:
```
use XRPL_PHP\Client\JsonRpcClient;

const LOCAL_JSON_RPC_URL = "http://localhost:5005/";
$client = new JsonRpcClient("LOCAL_JSON_RPC_URL");
```
See the example core server config file for more information about default values.

By using one of the available public servers:

use XRPL_PHP\Client\JsonRpcClient;

const MAINNET_JSON_RPC_URL = "https://s2.ripple.com:51234/";
$client = new JsonRpcClient("MAINNET_JSON_RPC_URL");

2. Get account

To store value and execute transactions on the XRP Ledger, you need to get an account: a set of keys and an address that's been funded with enough XRP to meet the account reserve. The address is the identifier of your account and you use the private key to sign transactions that you submit to the XRP Ledger. For production purposes, you should take care to store your keys and set up a secure signing method.

To generate a new account, PHP_XRPL provides the static generate() method in the Wallet class:

<?php

// Use the Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Imports 
use XRPL_PHP\Wallet\Wallet;

// Create a new wallet
$wallet = Wallet::generate();

The result returns a Wallet instance:

// print wallet properties
print_r([
  'publicKey' => $wallet->getPublicKey(),
  'privateKey' => $wallet->getPrivateKey(),
  'classicAddress' => $wallet->getAddress(),
  'seed' => $wallet->getSeed()
]);

// output
// Array
// (
//    [publicKey] => ED2C4CE69F663254840905AEF5FB8596FC243EDEBE0295A6ECEE86CE8EB8F76210
//    [privateKey] => -HIDDEN-
//    [classicAddress] => rBi9u1P3ofRKTFPFTgrguANz2wRqsdKHvm
//    [seed] => -HIDDEN-
//)

For testing and development purposes, you can use the fundWallet() helper function on the XRP Ledger Testnet:

?php

// Use the Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Imports
use XRPL_PHP\Client\JsonRpcClient;
use XRPL_PHP\Models\Account\AccountInfoRequest;
use XRPL_PHP\Wallet\Wallet;
use function XRPL_PHP\Sugar\fundWallet;

// Create a client using the Testnet
$client = new JsonRpcClient("https://s.altnet.rippletest.net:51234");

// Create a new wallet
$wallet = Wallet::generate();

// Fund (and activate) the wallet
fundWallet($client, $wallet);

3. Query the XRP Ledger

You can query the XRP Ledger to get information about a specific account, a specific transaction, the state of a current or a historical ledger, and the XRP Ledger's decentralized exchange. You need to make these queries, among other reasons, to look up account info to follow best practices for reliable transaction submission.

Here, we'll use the JsonRpcClient we constructed to look up information about the account we got in the previous step.

// Create an AccountInfoRequest method
$accountInfoRequest = new AccountInfoRequest(
    account: $wallet->getAddress(),
    ledgerIndex: 'validated'
 );

//  Send the request to the XRPL
$accountInfoResponse = $client->syncRequest($accountInfoRequest);

// Print formatted response
print_r($accountInfoResponse);

4. Starting the script

Now, we have a simple application that:

Creates an account on the Testnet.
Connects to the XRP Ledger.
Looks up and prints information about the account you created.

To run the app, you can copy the code from this website's GitHub Repository and run it from the command line:

composer require hardcastle/xrpl_php
php get-account-info.php

You should see output similar to this example:

XRPL_PHP\Models\Account\AccountInfoResponse Object
(
    [id:protected] => 
    [result:protected] => Array
        (
            [account_data] => Array
                (
                    [Account] => rDTRjR6sWrRmGe18KMVwBuL212gLpArVLy
                    [Balance] => 10000000000
                    [Flags] => 0
                    [LedgerEntryType] => AccountRoot
                    [OwnerCount] => 0
                    [PreviousTxnID] => AE18C0B30DE740490E66E92D9F45162C8860A6D9FCF279CF7A51FAFE05F573FB
                    [PreviousTxnLgrSeq] => 42719256
                    [Sequence] => 42719256
                    [index] => 4DD9F7FAE7365B7A917932D6453DBA9B223AA4FF7193691EF6E5EE230519F4CA
                )

            [account_flags] => Array
                (
                    [defaultRipple] => 
                    [depositAuth] => 
                    [disableMasterKey] => 
                    [disallowIncomingCheck] => 
                    [disallowIncomingNFTokenOffer] => 
                    [disallowIncomingPayChan] => 
                    [disallowIncomingTrustline] => 
                    [disallowIncomingXRP] => 
                    [globalFreeze] => 
                    [noFreeze] => 
                    [passwordSpent] => 
                    [requireAuthorization] => 
                    [requireDestinationTag] => 
                )

            [ledger_hash] => 57F0CB8311CDEAE9AC60854CC482990CE971D1FD36DB1CC215B7A6634E27E739
            [ledger_index] => 42719256
            [status] => success
            [validated] => 1
        )

    [warnings:protected] => 
    [status:protected] => success
    [type:protected] => response
)

Interpreting the response

The response fields contained in AccountInfoResponse that you want to inspect in most cases are:

['account_data']['Sequence'] — This is the sequence number of the next valid transaction for the account. You need to specify the sequence number when you prepare transactions.
['account_data']['Balance'] — This is the account's balance of XRP, in drops. You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the current transaction cost for a given transaction.
['validated'] — Indicates whether the returned data is from a validated ledger. When inspecting transactions, it's important to confirm that the results are final before further processing the transaction. If validated is true then you know for sure the results won't change. For more information about best practices for transaction processing, see Reliable Transaction Submission.

For a detailed description of every response field, see account_info.

Keep on building

Now that you know how to use XRPL_PHP to connect to the XRP Ledger, get an account, and look up information about it, you can also use XRPL_PHP to:

Send XRP.
Set up secure signing for your account.