nbobtc/bitcoind-php 
, (*1)
NOTE: This is version 2.x of this project. There is a more stable version of
this on the 1.x branch., (*2)
This project is used to interact with a headless bitcoin program called
bitcoind. It also contains various utility classes for working with Bitcoin as a
PHP Developer., (*3)
Installation
You can install this library by using Composer. You can also view more info
about this on Packagist., (*4)
Add this to the require section in your composer.json file., (*5)
{
"require": {
"nbobtc/bitcoind-php": "~2.0@dev"
}
}
Usage
To use the project you need to just create a new instance of the class., (*6)
$command = new \Nbobtc\Command\Command('getinfo');
$client = new \Nbobtc\Http\Client('https://username:password@localhost:18332');
/** @var \Nbobtc\Http\Message\Response */
$response = $client->sendCommand($command);
/** @var string */
$contents = $response->getBody()->getContents();
You are able to get the [Request] and [Response] objects back from
the client with the correct getters: getRequest() and getResponse()., (*7)
You can also parse the response however you wish to do so since the result is
returned to you as a string. See below for some ideas!, (*8)
Commands
Commands are created in such a way that this will support any future updates the
Bitcoin API by providing you with an easy class that sets all the required
information., (*9)
You are able to pass into the object the method and the parameters that are
required. Here are a few examples:, (*10)
// No Parameters
$command = new Command('getinfo');
// One Parameters
$command = new Command('getblock', '000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f');
// Multiple Parameters
$command = new Command('sendfrom', array('fromaccount', 'tobitcoinaddress', 'amount'));
The second argument MUST be in the same order as on the Bitcoin API wiki page.
There is no need to assign the values any keys., (*11)
Parameters
Parameters are the second argument when creating a new Command. This argument
can either be a string OR an array. For example, both of these are valid., (*12)
$command = new Command('getblock', array('000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f'));
$command = new Command('getblock', '000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f');
Most commands in the Bitcoin API take one parameter. If it takes MORE than
one, you must pass the parameters in as an array in the ORDER you find them on
that page., (*13)
Curl Driver
Drivers are meant to be used with the client for connecting to a bitcoind
service. By default a CurlDriver is used. This provides you with some
flexibility on setting this up custom for your own configuration., (*14)
You can set various cURL Options by passing them into the function
addCurlOption($option, $value)., (*15)
Here's an example of how to configure and use the driver., (*16)
$driver = new \Nbobtc\Http\Driver\CurlDriver();
$driver
->addCurlOption(CURLOPT_VERBOSE, true)
->addCurlOption(CURLOPT_STDERR, '/var/logs/curl.err');
$client = new \Nbobtc\Http\Client('https://username:password@localhost:18332');
$client->withDriver($driver);
Feel free to take a look at the CurlDriver source code., (*17)
How to enable a Keep-Alive ie Persistent Connection
This example shows how you are able to set the client up to Persistent
Connection., (*18)
$client = new \Nbobtc\Http\Client('https://username:password@localhost:18332');
$client->getRequest()->withHeader('Connection', 'Keep-Alive');
How to set a CA Cert
This library provides some wonderful flexibility that will allow you to
configure the client to use your own CA Cert., (*19)
$driver = new \Nbobtc\Http\Driver\CurlDriver();
$driver->addCurlOption(CURLOPT_CAINFO, '/path/to/cert');
$client = new \Nbobtc\Http\Client('https://username:password@localhost:18332');
$client->withDriver($driver);
Convert Output to an Array
Some like the arrays, (*20)
$response = $client->sendCommand($command);
$output = json_decode($response->getBody()->getContents(), true);
Convert Output to a stdClass object
Some like the objects, (*21)
$response = $client->sendCommand($command);
$output = json_decode($response->getBody()->getContents());
Tests
To run the tests you need to install the development packages using composer, (*22)
php composer.phar install --dev
Once this is complete you can run phpunit, (*23)
./bin/phpunit
API Documentation
@TODO - Complete section on making API Documentation, (*24)
Change log
See CHANGELOG.md., (*25)
Contains information on releases such as what was added, changed, etc. It's good
to look at to see what has changed from release to release., (*26)
Contributing
See CONTRIBUTING.md., (*27)
Various ways on contributing to this project., (*28)
Branching
2.x
Current production branch. All 2.x tags come off of this branch., (*29)
master
This is the latest and greatest, it should not be used an is considered
development for testing new features and functionality., (*30)
1.x
Deprecated, only used for bug fixes and for historical records., (*31)
Releasing
You can find a complete list of Releases on GitHub., (*32)
Checklist
- [ ] Update
composer.json with new minor or patch increase.
- [ ] Update CHANGELOG.md with release info and get rid of unreleased section.
- [ ] Make tag and push tag up.
- [ ] Copy section in CHANGELOG.md that pertains to the release and add info to
release docs on GitHub.
- [ ] Update CHANGELOG.md with unreleased section
Copyright (C) 2012-2014 Joshua Estes, (*33)
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:, (*34)
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software., (*35)
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE., (*36)
Wallogit.com
