PHPackages                             extraton/php-ton-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. extraton/php-ton-client

ActiveLibrary[Utility & Helpers](/categories/utility)

extraton/php-ton-client
=======================

Extraton, PHP TON client

1.23.1(4y ago)259368Apache-2.0PHPPHP ^7.4|^8.0

Since Nov 15Pushed 4y ago3 watchersCompare

[ Source](https://github.com/extraton/php-ton-client)[ Packagist](https://packagist.org/packages/extraton/php-ton-client)[ Docs](https://extraton.io/)[ RSS](/packages/extraton-php-ton-client/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (4)Versions (38)Used By (0)

[![Extraton, PHP TON Client](.github/extraton_elephant.png?raw=true)](.github/extraton_elephant.png?raw=true)

Extraton, PHP TON Client
========================

[](#extraton-php-ton-client)

[![php7.4, Ubuntu 20.04](https://github.com/extraton/php-ton-client/workflows/php7.4,%20Ubuntu%2020.04/badge.svg)](https://github.com/extraton/php-ton-client/actions?query=workflow%3A%22php7.4%2C+Ubuntu+20.04%22)[![php7.4, macOS latest](https://github.com/extraton/php-ton-client/workflows/php7.4,%20macOS%20latest/badge.svg)](https://github.com/extraton/php-ton-client/actions?query=workflow%3A%22php7.4%2C+macOS+latest%22)[![Total Downloads](https://camo.githubusercontent.com/798f3ec1fd962dd550b0328a9a2b0c29b9a5ca3b6f5cc71195cf939b78f3b736/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6578747261746f6e2f7068702d746f6e2d636c69656e742e7376673f7374796c653d666c617426636f6c6f723d303065363030)](https://packagist.org/packages/extraton/php-ton-client) [![Chat on Telegram](https://camo.githubusercontent.com/a8a99593f104405b78c16dcd3ccd82a1b8b5feabe962029ad94bf8e62f043cb6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636861742d6f6e25323054656c656772616d2d3963662e7376673f6c6f676f3d74656c656772616d26636f6c6f723d303038386363)](https://t.me/extraton)

**Extraton** is a simple and powerful php-library to binding with the [TON SDK](https://github.com/tonlabs/TON-SDK). It allows to interact with FreeTON blockchain. It has the rich abilities:

- All methods of the TON SDK v1.0.0 are implemented
- Interaction with the TON SDK through an asynchronous calls
- The every method contains inline-doc
- The full autocomplete is available in a such IDE like the [PHPStorm](https://www.jetbrains.com/phpstorm/)
- Simple installation by the [Composer](https://getcomposer.org/) package manager
- The automatic download of the TON SDK library for the current environment
- The client auto configuration (out-of-the-box)
- Covered by the unit-tests
- Fully covered by the integration tests
- Tools to maintain code quality (static analyser and codestyle checker)
- Tools to the quick start to develop (see [Dockerfile](Dockerfile) + [Makefile](Makefile))
- The error handling by the general exception interface (see [src/Exception](src/Exception))
- Using generators to iterate the asynchronous events
- You can add your own client implementation based on [FFIAdapter](src/FFI/FFIAdapter.php) and [Binding](src/Binding/Binding.php)
- A simple interface to the graphql requests
- Temporary logs creation for the detailed analysis on integration tests running

Requirements
------------

[](#requirements)

- php7.4+ or php8.0+
- ffi extension
- json extension
- zlib extension
- TON SDK Library **1.22.0** (download script included)

Installation
------------

[](#installation)

To install it via [Composer](https://getcomposer.org/) simply run:

```
composer require extraton/php-ton-client
```

To automatically download the TON SDK library add the following lines to your project `composer.json` file:

```
...
  "scripts": {
    "download-ton-sdk-library": "Extraton\\TonClient\\Composer\\Scripts::downloadLibrary",
    "post-update-cmd": [
      "@download-ton-sdk-library"
    ],
    "post-install-cmd": [
      "@download-ton-sdk-library"
    ]
  }
...
```

The library will be downloaded after the commands `composer install` or `composer update` are called in your project root. To forced download the TON SDK library for your operating system, run the following command:

```
composer run download-ton-sdk-library
```

The TON SDK library will be installed to the directory `YOUR_PROJECT_ROOT/vendor/extranton/php-ton-client/bin/`.

Configuring
-----------

[](#configuring)

Simple TonClient instantiation:

```
$tonClient = TonClient::createDefault();
```

It uses the default configuration:

```
$config = [
    "network" => [
        'server_address'             => 'net.ton.dev',
        'network_retries_count'      => 5,
        'message_retries_count'      => 5,
        'message_processing_timeout' => 60000,
        'wait_for_timeout'           => 60000,
        'out_of_sync_threshold'      => 30000,
        'access_key'                 => ''
    ],
    'abi'     => [
        'workchain'                              => 0,
        'message_expiration_timeout'             => 60000,
        'message_expiration_timeout_grow_factor' => 1.35
    ],
    'crypto'  => [
        'mnemonic_dictionary'   => 1,
        'mnemonic_word_count'   => 12,
        'hdkey_derivation_path' => "m/44'/396'/0'/0/0",
        'hdkey_compliant'       => true
    ],
];
```

You can start using a simple configuration for TonClient:

```
$config = [
    'network' => [
        'server_address' => 'net.ton.dev'
    ]
];
```

All configuration options are available [here](https://github.com/tonlabs/TON-SDK/blob/1.0.0/docs/mod_client.md#ClientConfig). After instantiate the TonClient will automatically detect operating system and path to the TON SDK library:

```
// Create new instance with custom configuration and default path to TON SDK library
$tonClient = new TonClient($config);
```

Default path: `YOUR_PROJECT_ROOT/vendor/extraton/bin/tonclient.*`. Also you can specify path by the following lines of code:

```
// Create new instance TonClient with custom path to TON SDK library
$binding = new Binding('PATH_TO_TON_SDK_LIBRARY');
$tonClient = new TonClient($config, $binding);
```

Basic usage
-----------

[](#basic-usage)

```
// Get TON SDK version
$result = $tonClient->version();

echo "TON SDK version: " , $result->getVersion() . PHP_EOL;
```

```
// Get instance of Crypto module
$crypto = $tonClient->getCrypto();

// Generate random key pair
$result = $crypto->generateRandomSignKeys();
$keyPair = $result->getKeyPair();

echo 'Public key: ' . $keyPair->getPublic() . PHP_EOL;
echo 'Private key: ' . $keyPair->getSecret() . PHP_EOL;
```

```
// Get instance of Utils module
$utils = $tonClient->getUtils();

// Convert address to hex format
$result = $utils->convertAddressToHex('ee65d170830136253ad8bd2116a28fcbd4ac462c6f222f49a1505d2fa7f7f528');

echo 'Hex: ' . $result->getAddress() . PHP_EOL;
```

Building queries
----------------

[](#building-queries)

Use special classes to easily build queries:

```
$query = (new ParamsOfWaitForCollection('accounts'))
   ->addResultField('id', 'last_paid')
   ->addFilter('last_paid', Filters::IN, [1601332024, 1601331924])
   ->setTimeout(60_000);

$net->waitForCollection($query);
```

```
$query = (new ParamsOfSubscribeCollection('transactions'))
    ->addResultField('id', 'block_id', 'balance_delta')
    ->addFilter('balance_delta', Filters::GT, '0x5f5e100');

$net->subscribeCollection($query);
```

```
$query = new ParamsOfQueryCollection('accounts');
$query->addResultField(
    'acc_type',
    'acc_type_name',
    'balance',
    'boc',
    'id',
    'last_paid',
    'workchain_id',
);
$query->addFilter(
    'last_paid',
    Filters::IN,
    [
        1601332024,
        1601331924,
        1601332491,
        1601332679
    ]
);
$query->addOrderBy('last_paid', OrderBy::DESC)->setLimit(2);

$net->queryCollection($query);
```

You can add your own query class that implements the interface `\Extraton\TonClient\Entity\Net\QueryInterface` or extends the class `\Extraton\TonClient\Entity\Net\AbstractQuery`.

The following constants are available for filters and directions:

```
class Filters implements Params
{
    public const EQ = 'eq';
    public const GE = 'ge';
    public const GT = 'gt';
    public const IN = 'in';
    public const LE = 'le';
    public const LT = 'lt';
    public const NE = 'ne';
    public const NOT_IN = 'notIn';
...
```

```
class OrderBy implements Params
{
    public const ASC = 'ASC';
    public const DESC = 'DESC';
...
```

Advanced usage
--------------

[](#advanced-usage)

Use the following example to build an application for monitoring events coming from the blockchain network:

```
// Build query
$query = (new ParamsOfSubscribeCollection('transactions'))
    ->addResultField('id', 'block_id', 'balance_delta')
    ->addFilter('balance_delta', Filters::GT, '0x5f5e100');

// Get result with handle and start watching
$result = $net->subscribeCollection($query);

echo "Handle: {$result->getHandle()}." . PHP_EOL;

$counter = 0;

// Iterate generator
foreach ($result->getIterator() as $event) {
    $counter++;

    echo "Event counter: {$counter}, event data:" . PHP_EOL;
    var_dump($event->getResult());

    if ($counter > 25) {
        echo 'Manual stop watching.' . PHP_EOL;
        $result->stop(); // or call: $net->unsubscribe($result->getHandle());
    }
}

echo 'Finished.' . PHP_EOL;
```

[Detailed example](examples/net_subscribe_collection.php)

Examples
--------

[](#examples)

Please see [Examples](examples) and [Integration tests](tests/Integration) for more information on detailed usage.

⚠️ Warning
----------

[](#️-warning)

We use experemental [PHP extension FFI](https://www.php.net/manual/en/book.ffi.php). This extension allows the loading of shared libraries, calling of C functions and accessing of C data structures in pure PHP. **This is the only one possible way to async integrate with the TON SDK library.**

Please read **the official warnings** from the developers of php:

> Warning This extension is EXPERIMENTAL. The behaviour of this extension including the names of its functions and any other documentation surrounding this extension may change without notice in a future release of PHP. This extension should be used at your own risk.

[FFI Introduction](https://www.php.net/manual/en/intro.ffi.php)

> Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.

[PHP Callbacks](https://www.php.net/manual/en/ffi.examples-callback.php)

We have not detected memory leaks. But sometimes we caught segmentation faults during testing. 🙏 Hopefully the FFI extension will be stabilized in future versions of php.

Change log
----------

[](#change-log)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Testing
-------

[](#testing)

Run the following command to run unit tests:

```
make test-unit
```

... and integration tests:

```
make test-integration
```

Some tests use TON SDK methods that listen for asynchronous events. Data from these events is saved to the directory `/tests/Integration/artifacts/`. This way you can analyze them in detail. For example, the test `\Extraton\Tests\Integration\TonClient\ProcessingTest::testProcessMessageWithEvents` uses the call of method `\Extraton\TonClient\Processing::processMessage`. Events received during generator iteration are saved in a file.

Code Quality
------------

[](#code-quality)

We use [PHPStan](https://github.com/phpstan/phpstan) and [PHP Coding Standards Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) to control code quality. Run the following commands to analyze the code and fix code style errors:

```
make analyze
```

```
make codestyle
```

```
make codestyle-fix
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Notice
------

[](#notice)

If you have any issues, just feel free and open it in this repository, thx!

Credits
-------

[](#credits)

- [Maxim Karanaev](https://github.com/maxvx)
- [qwertys318](https://github.com/qwertys318)

License
-------

[](#license)

The Apache License Version 2.0. Please see [License File](LICENSE) for more information.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity26

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 92.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Recently: every ~23 days

Total

37

Last Release

1630d ago

Major Versions

0.0.6 → 1.0.02020-11-17

PHP version history (2 changes)0.0.1PHP ^7.4

1.2.0PHP ^7.4|^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/754038?v=4)[Maxim Karanaev](/maintainers/maxvx)[@maxvx](https://github.com/maxvx)

---

Top Contributors

[![maxvx](https://avatars.githubusercontent.com/u/754038?v=4)](https://github.com/maxvx "maxvx (96 commits)")[![qwertys318](https://avatars.githubusercontent.com/u/8297111?v=4)](https://github.com/qwertys318 "qwertys318 (7 commits)")[![SaloEater](https://avatars.githubusercontent.com/u/6031470?v=4)](https://github.com/SaloEater "SaloEater (1 commits)")

---

Tags

blockchainffi-extensionfreetonphptonton-sdk-librarytondappextratonfreetonton crystal

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/extraton-php-ton-client/health.svg)

```
[![Health](https://phpackages.com/badges/extraton-php-ton-client/health.svg)](https://phpackages.com/packages/extraton-php-ton-client)
```

###  Alternatives

[google/cloud-core

Google Cloud PHP shared dependency, providing functionality useful to all components.

343121.4M79](/packages/google-cloud-core)[typo3/cms-install

TYPO3 CMS Install Tool - The Install Tool is used for installation, upgrade, system administration and setup tasks.

1811.5M309](/packages/typo3-cms-install)[olifanton/ton

PHP library for The Open Network blockchain

8849.8k2](/packages/olifanton-ton)[laracrafts/laravel-url-shortener

Powerful URL shortening tools in Laravel

97110.7k](/packages/laracrafts-laravel-url-shortener)[recca0120/laravel-parallel

64116.7k](/packages/recca0120-laravel-parallel)[phpcfdi/cfdi-sat-scraper

Web Scraping para extraer facturas electrónicas desde la página del SAT

9018.0k](/packages/phpcfdi-cfdi-sat-scraper)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)