You can install this library via Composer: composer require bluzelle/blzphp
In general, you must initialize blzphp before calling any other functions. Do the following using your own configuration parameters as applicable to initialize:
blz = new Bluzelle\Client('account', 'mnemonic', 'endpoint', 'chainId', 'uuid');This performs some initial checks, retrieves your account information, and returns an object through which you can call the rest of the API functions.
You may now use the functions described below to perform database operations, as well as retrieve account and status information.
Read below for detailed documentation on how to use the Bluzelle database service.
Configures the Bluzelle connection. Multiple clients can be created by creating new instances of this class.
use Bluzelle\Client;
api = new Client(
'bluzelle1xhz23a58mku7ch3hx8f9hrx6he6gyujq57y3kp',
'volcano arrest ceiling physical concert sunset absent hungry tobacco canal census era pretty car code crunch inside behind afraid express giraffe reflect stadium luxury',
"http://localhost:1317",
"20fc19d4-7c9d-4b5c-9578-8cedd756e0ea",
"bluzelleTestPublic-1"
);| Argument | Description |
|---|---|
| address | The address of your Bluzelle account |
| mnemonic | The mnemonic of the private key for your Bluzelle account |
| endpoint | (Optional) The hostname and port of your rest server. Default: http://localhost:1317 |
| uuid | (Optional) Bluzelle uses UUID's to identify distinct databases on a single swarm. We recommend using Version 4 of the universally unique identifier. Defaults to the account address. |
| chain_id | (Optional) The chain id of your Bluzelle account. Default: bluzelle |
The calls below are methods of the instance created by instantiating the Bluzelle::Swarm::Client class.
Retrieve the version of the Bluzelle service.
api->version();Returns a promise resolving to a string containing the version information, e.g.
0.0.0-39-g8895e3e
Throws an exception if a response is not received from the connection.
Retrieve information about the currently active Bluzelle account.
api->account();Returns a promise resolving to a JSON object representing the account information, e.g.
Throws an exception if a response is not received from the connection.
Create a field in the database.
api->create('mykey', '{ a: 13 }', ['gax_fee' => '400001'], ['days' => 100]);| Argument | Description |
|---|---|
| key | The name of the key to create |
| value | The string value to set the key |
| gas_info | Object containing gas parameters (see above) |
| lease_info (optional) | Minimum time for key to remain in database (see above) |
Returns a promise resolving to nothing.
Throws an exception when a response is not received from the connection, the key already exists, or invalid value.
Retrieve the value of a key without consensus verification. Can optionally require the result to have a cryptographic proof (slower).
value = api->read('mykey');| Argument | Description |
|---|---|
| key | The key to retrieve |
| prove | A proof of the value is required from the network (requires 'config trust-node false' to be set) |
Returns a promise resolving the string value of the key.
Throws an exception when the key does not exist in the database. Throws an exception when the prove is true and the result fails verification.
Retrieve the value of a key via a transaction (i.e. uses consensus).
value = api->txRead('mykey', ['max_fee' => '400001']);| Argument | Description |
|---|---|
| key | The key to retrieve |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving the string value of the key.
Throws an exception when the key does not exist in the database.
Update a field in the database.
api->update('mykey', '{ a: 13 }', ['max_fee': '400001'], ['days' => 100]);| Argument | Description |
|---|---|
| key | The name of the key to create |
| value | The string value to set the key |
| gas_info | Object containing gas parameters (see above) |
| lease_info (optional) | Positive or negative amount of time to alter the lease by. If not specified, the existing lease will not be changed. |
Returns a promise resolving to nothing.
Throws an exception when the key doesn't exist, or invalid value.
Delete a field from the database.
api->delete('mykey', ['max_fee' => '400001']);| Argument | Description |
|---|---|
| key | The name of the key to delete |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to nothing.
Throws an exception when the key is not in the database.
Query to see if a key is in the database. This function bypasses the consensus and cryptography mechanisms in favor of speed.
hasMyKey = api->has('mykey');| Argument | Description |
|---|---|
| key | The name of the key to query |
Returns a promise resolving to a boolean value - true or false, representing whether the key is in the database.
Query to see if a key is in the database via a transaction (i.e. uses consensus).
hasMyKey = api->txHas('mykey', ['gas_price' => 10]);| Argument | Description |
|---|---|
| key | The name of the key to query |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to a boolean value - true or false, representing whether the key is in the database.
Retrieve a list of all keys. This function bypasses the consensus and cryptography mechanisms in favor of speed.
keys = api->keys();Returns a promise resolving to an array of strings. ex. ["key1", "key2", ...].
Retrieve a list of all keys via a transaction (i.e. uses consensus).
keys = api->txKeys([ 'gas_price' => 10]);| Argument | Description |
|---|---|
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to an array of strings. ex. ["key1", "key2", ...].
Change the name of an existing key.
api->rename('key', 'newkey', ['gas_price' => 10]);| Argument | Description |
|---|---|
| key | The name of the key to rename |
| new_key | The new name for the key |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to nothing.
Throws an exception if the key doesn't exist.
| Argument | Description |
|---|---|
| key | The name of the key to query |
Returns a promise resolving to a boolean value - true or false, representing whether the key is in the database.
Retrieve the number of keys in the current database/uuid. This function bypasses the consensus and cryptography mechanisms in favor of speed.
number = api->count();Returns a promise resolving to an integer value.
Retrieve the number of keys in the current database/uuid via a transaction.
number = api->txCount(['gas_price' => 10]);| Argument | Description |
|---|---|
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to an integer value.
Remove all keys in the current database/uuid.
api->deleteAll([gas_price => 10]);| Argument | Description |
|---|---|
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to nothing.
Enumerate all keys and values in the current database/uuid. This function bypasses the consensus and cryptography mechanisms in favor of speed.
kvs = api->keyValues();Returns a promise resolving to a JSON array containing key/value pairs, e.g.
[{"key": "key1", "value": "value1"}, {"key": "key2", "value": "value2"}]
Enumerate all keys and values in the current database/uuid via a transaction.
kvs = api->txKeyValues(['gas_price' => 10]);| Argument | Description |
|---|---|
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to a JSON array containing key/value pairs, e.g.
[{"key": "key1", "value": "value1"}, {"key": "key2", "value": "value2"}]
Update multiple fields in the database.
api->multiUpdate([['key' => "key1", 'value' => "value1"], ['key' => "key2", 'value' => "value2"], ['gas_price': 10]]);| Argument | Description |
|---|---|
| key_values | An array of objects containing keys and values (see example avove) |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving to nothing.
Throws an exception when any of the keys doesn't exist.
Retrieve the minimum time remaining on the lease for a key. This function bypasses the consensus and cryptography mechanisms in favor of speed.
value = api->getLease('mykey');| Argument | Description |
|---|---|
| key | The key to retrieve the lease information for |
Returns a promise resolving the minimum length of time remaining for the key's lease, in seconds.
Throws an exception when the key does not exist in the database.
Retrieve the minimum time remaining on the lease for a key, using a transaction.
value = api->txGetLease('mykey', ['gas_price' => 10]);| Argument | Description |
|---|---|
| key | The key to retrieve the lease information for |
| gas_info | Object containing gas parameters (see above) |
Returns a promise resolving the minimum length of time remaining for the key's lease, in seconds.
Throws an exception when the key does not exist in the database.
Update the minimum time remaining on the lease for a key.
value = api->renewLease('mykey', ['max_fee' => '400001'], [ 'days' => 100 ]);| Argument | Description |
|---|---|
| key | The key to retrieve the lease information for |
| gas_info | Object containing gas parameters (see above) |
| lease_info (optional) | Minimum time for key to remain in database (see above) |
Returns a promise resolving the minimum length of time remaining for the key's lease.
Throws an exception when the key does not exist in the database.
Update the minimum time remaining on the lease for all keys.
value = api->renewLeaseAll(['max_fee' => '400001'], [ 'days' => 100 ]);| Argument | Description |
|---|---|
| gas_info | Object containing gas parameters (see above) |
| lease_info (optional) | Minimum time for key to remain in database (see above) |
Returns a promise resolving the minimum length of time remaining for the key's lease.
Throws an exception when the key does not exist in the database.
Retrieve a list of the n keys in the database with the shortest leases. This function bypasses the consensus and cryptography mechanisms in favor of speed.
keys = api->getNShortestLease(10);| Argument | Description |
|---|---|
| n | The number of keys to retrieve the lease information for |
Returns a JSON array of objects containing key, lease (in seconds), e.g.
[ { key: "mykey", lease: { seconds: "12345" } }, {...}, ...]
Retrieve a list of the N keys/values in the database with the shortest leases, using a transaction.
keys = api.txGetNShortestLease(10, ['max_fee' => '400001']);| Argument | Description |
|---|---|
| n | The number of keys to retrieve the lease information for |
| gas_info | Object containing gas parameters (see above) |
Returns a JSON array of objects containing key, lifetime (in seconds), e.g.
[ { key: "mykey", lifetime: "12345" }, {...}, ...]
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to phpgems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/mul53/bluzelle. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Bluzelle project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.