zorn-v/php-electrum-api

PHP wrapper for Electrum JSONRPC-API

, _(*1)

php-electrum-api - Electrum library

Licence: GPL-3.0
Author: Pascal Krason <p.krason@padr.io>
Language: PHP 5.6-7.1

Please note, this library is by far not completed and but can be used in production. Until now i only implemented the most commonly used API-Calls. If you think im missing something, just create an issue or fork the project., _(*2)

Setting up Electrum

First you need to setup a new Electrum wallet. Follow the instructions according to your OS at the Electrum Download Page. After the successfull installation you need to set a rpcport by typing:, _(*3)

electrum setconfig rpcport 7777
electrum setconfig rpcuser "username"
electrum setconfig rpcpassword "password"

Then we can create a default wallet, dont forget to note your generated seed, it's nescessary if you want to recover it one day:, _(*4)

electrum create

Now we can go ahead and start Electrum in daemon mode:, _(*5)

electrum daemon start

Since some new version electrum wants you to load your wallet by hand on startup:, _(*6)

electrum daemon load_wallet

Requirements

On the PHP side there are not much requirements, you only need at least PHP 5.6 and the curl-Extension installed. Then you can go ahead ans it through Composer which will do everything else for you., _(*7)

Install

First you need to install Composer, after you accomplished this you can go ahead:, _(*8)

composer require padrio/php-electrum-api

Then you can simply include the autoloader and begin using the library:, _(*9)

// Include composer autoloader
require_once 'vendor/autoloader.php';

Examples

Basic example

A very basic useage example. Every API-Call has it's own request-object. You simply create one and execute it., _(*10)

$method = new \Electrum\Request\Method\Version();

try {
    $response = $method->execute();
} catch(\Exception $exception) {
    die($exception->getMessage());
}

$response->getVersion();

Create new wallet

Create default wallet:, _(*11)

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $wallet = new \Electrum\Request\Method\Wallet\CreateWallet($client);
    $response = $wallet->execute();

This code is similar to the command:, _(*12)

$ electrum create

You can also create more wallets with custom names specifying flag of the new wallet., _(*13)

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $wallet = new \Electrum\Request\Method\Wallet\CreateWallet($client);
    $response = $wallet->execute(['wallet_path' => '~/.electrum/wallets/your_wallet']);

This code is similar to the command:, _(*14)

$ electrum create -w ~/.electrum/wallets/your_wallet

Response will be:, _(*15)

[
    'seed' => 'wallet seed',
    'path' => 'path where wallet file is stored',
    'msg'  => 'Please keep your seed in a safe place; if you lose it, you will not be able to restore your wallet.',
];

Load wallet

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $load_wallet = new \Electrum\Request\Method\Wallet\LoadWallet($client);
    $load_wallet->execute(['wallet_path' => '~/.electrum/wallets/your_wallet']);
````

## List wallets

Get list of all loaded wallets:
```php
    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $list_wallets = new \Electrum\Request\Method\Wallet\ListWallets($client);
    $list_wallets->execute();

Get new address

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $wallet = new \Electrum\Request\Method\Payment\AddRequest($client);
    $tx     = $wallet->execute();
    echo $tx->getAddress();

Create new address for wallet

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $newAddress = new \Electrum\Request\Method\Address\CreateNewAddress($client);
    $newAddress->execute(['wallet'  => '~/.electrum/wallets/your_wallet']);

Make a new Payment

    $client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'user', 'password');
    $method = new \Electrum\Request\Method\Payment\PayTo($client);
    $method->setDestination('BTC4ddress1234'); //Destination parameter is the address where we'll send the btc
    $method->setAmount(1); //send 1 BTC = 10k usd

    $tx = $method->execute(); //$tx returns the transaction ID of the payment, this is still not sent to the blockchain
    /**
    * @param array ['password' => '<password>']
    * If the Electrum wallet is encrypted with a password use the following execute method instead
    * The previous one will return an error of "Password required"
    */
    //$tx = $method->execute(['password' => 'myPass123']); //

    $broadcast = new Electrum\Request\Method\Payment\Broadcast($client);
    $broadcast->setTransaction($tx);
    $result = $broadcast->execute(); //broadcasts payment to the blockchain
    echo $result;

    A payment has been made

Custom Client Configuration

Every Request/Method takes a Electrum\Client-instance as parameter which replaces the default one. A custom instance can be usefull if you want to set custom config params like another Hostname or Port., _(*16)

$client = new \Electrum\Client('http://127.0.0.1', 7777, 0, 'username', 'password');
$method = new \Electrum\Request\Method\Version($client);

try {
    $response = $method->execute();
} catch (\Exception $exception) {
    die($exception->getMessage());
}

$response->getVersion();

Advanced exception handling

Dealing with exceptions is easy. You can catch two types of exceptions which indicates whether it's an Request or Response fault., _(*17)

$method = new \Electrum\Request\Method\Version();

try {
    $response = $method->execute();
} catch (\Electrum\Request\Exception\BadRequestException $exception) {
    die(sprintf(
        'Failed to send request: %s',
        $exception->getMessage()
    ));
} catch(\Electrum\Response\Exception\BadResponseException $exception) {
    die(sprintf(
        'Electrum-Client failed to respond correctly: %s',
        $exception->getMessage()
    ));
}