Difference between revisions of "PHP developer intro"

From Bitcoin Wiki
Jump to: navigation, search
(Removed bad advice RE: using a hacked bitcoind)
(Trying not to scare people with unnecessary "download this, install that" crap)
Line 47: Line 47:
 
== Precision ==
 
== Precision ==
  
Because PHP has no option to JSON decode to accurate decimal class, you should internally use GMP. Treat each number like a large int with 8 decimal places (this can be trimmed for display).
+
Bitcoin amounts can range from 0.00000001 to 21,000,000.  To avoid rounding errors, you must make sure your PHP implementation supports the full range of bitcoin values without losing precision.  Most PHP implementations use IEEE 64-bit double-precision floating point numbers, which have 53 bits of precision, which is enough to correctly represent the full range of bitcoin values.
  
Our version of Bitcoin treats every monetary value as int64 8 decimal strings. So 1 BTC will be "100000000". Use PHP's GMP functions to manipulate these values accurately.
+
See [[Proper Money Handling (JSON-RPC)]] for more information.
  
For converting between internal GMP numbers and display/user input, you can use these functions:
+
If your PHP implementation does not support 64-bit numbers, you must use a version of bitcoind that sends values as strings and use the   [http://php.net/manual/en/ref.gmp.php GMP] and [http://php.net/manual/en/ref.bc.php BC Math] for all calculations involving bitcoin amounts.
<source lang="php">
 
# converts a user supplied number to our internal representation
 
#  3.14 => "314000000"
 
# accepts strings, floats and ints as input
 
function numstr_to_internal($numstr)
 
{
 
    return bcmul($numstr, pow(10, 8), 0);
 
}
 
# converts an internal number to an end user number for display as defined by precision
 
#  314100000 => "3.14"
 
# accepts GMP numbers, ints and strings as input
 
function internal_to_numstr($num, $precision=2)
 
{
 
    $repr = gmp_strval($num);
 
    $repr = bcdiv($repr, pow(10, 8), $precision);
 
    # now tidy output...
 
    # trim trailing 0s
 
    $repr = rtrim($repr, '0');
 
    # and a trailing . if it exists
 
    $repr = rtrim($repr, '.');
 
    return $repr;
 
}
 
 
 
$num_internal = numstr_to_internal("3.141");
 
echo "<p>".$num_internal."</p>";
 
$num_display = internal_to_numstr($num_internal);
 
echo "<p>".$num_display."</p>";
 
</source>
 
 
 
If you need to do a decimal division in GMP, then GMP only supports integer division + a remainder ([http://php.net/manual/en/function.gmp-div-qr.php gmp_div_qr]). The work-around for this, is to use the bcmath module:
 
<source lang="php">
 
$a = gmp_init("100");
 
$b = gmp_init("3");
 
echo "<p>".bcdiv(gmp_strval($a), gmp_strval($b), 3)."</p>";
 
</source>
 
 
 
Note that bcdiv uses strings.
 
 
 
See also: [http://php.net/manual/en/ref.gmp.php GMP] and [http://php.net/manual/en/ref.bc.php BC Math] manuals.
 
  
 
== Accounts ==
 
== Accounts ==

Revision as of 12:00, 30 March 2011

Linux Apache MySQL PHP + Bitcoin tutorial.

For the sake of this tutorial we assume an Ubuntu server running with PHP. The use case here is integrating a shopping system to accept Bitcoins. We assume some knowledge of Bitcoin and experience in PHP.

You can substitute any other language here for PHP. See the associated API reference pages for info on other languages.

You will run Bitcoin in daemon mode. The way PHP communicates is through localhost HTTP requests. You use a library called JSON-RPC to call the various functions. It will respond back with a JSON object.

Setting up Bitcoin

You need the bitcoind command-line daemon. You can either compile it from source or download a binary from the bitcoin.org homepage.

See Running Bitcoin for details on configuring bitcoin.

Before running bitcoind you will need to create a file in the bitcoin data directory (~/.bitcoin/.bitcoin.conf on Linux):

rpcuser=user
rpcpassword={you MUST pick a unique password to be secure}

Now run bitcoind:

$ ./bitcoind
# wait a few seconds for it to start up
$ ./bitcoind getinfo
# various info shown
$ ./bitcoind help
# help on commands

Bitcoin is now initialising and you must wait until "blocks" is at the current count.

First steps

Assuming Bitcoin has finished the initialisation process; download the file jsonRPCClient.php from JSON-RPC PHP. The other files can be safely discarded.

  require_once 'jsonRPCClient.php';
  
  $bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');
   
  echo "<pre>\n";
  print_r($bitcoin->getinfo());
  echo "</pre>";

Precision

Bitcoin amounts can range from 0.00000001 to 21,000,000. To avoid rounding errors, you must make sure your PHP implementation supports the full range of bitcoin values without losing precision. Most PHP implementations use IEEE 64-bit double-precision floating point numbers, which have 53 bits of precision, which is enough to correctly represent the full range of bitcoin values.

See Proper Money Handling (JSON-RPC) for more information.

If your PHP implementation does not support 64-bit numbers, you must use a version of bitcoind that sends values as strings and use the GMP and BC Math for all calculations involving bitcoin amounts.

Accounts

In Bitcoin, money is sent to addresses. Your balance is the total of all the money in all the address in your wallet.

Bitcoin goes another step. You can have accounts. Each account holds multiple addresses and adds like a mini-Bitcoin.

$ ./bitcoind listaccounts
# show list of accounts and various info for each one
$ ./bitcoind getaccountaddress user889
# get an address to receive money to that is unique for the account user889
$ ./bitcoind getbalance user889
# get the sum of all the money in the addresses owned by the account user889

In your shopping system, each user should have a unique username. You then query bitcoin for a unique address using $bitcoin->getaccountaddress("user889"); [gets the first address for user889] or $bitcoin->getnewaddress("user889"); [creates a new address for user889].

The customer then deposits to this address.

You can check the funds for that customer by doing $bitcoin->getbalance("user889", 4);. The 4 indicates the minimum number of confirmations we will accept before assuming this payment is valid.

getnewaddress vs getaccountaddress

Using getnewaddress helps increase the anonymity of your customers by making it hard to track their payments from the POV of a malicious agent. However running it too often will cause your wallet to become filled with many empty addresses.

I recommend that you run do something like:

<?php
    require_once('jsonRPCClient.php');
    $bitcoin = new jsonRPCClient('http://root:root@127.0.0.1:8332/'); 
    # now check for appropriate funds in user account
    try {
        $username = ...
        if(isset($_SESSION['sendaddress']))
            $sendaddress = $_SESSION['sendaddress'];
        else {
            $sendaddress = $bitcoin->getnewaddress($username);
            $_SESSION['sendaddress'] = $sendaddress;
        }
        $balance = $bitcoin->getbalance($username);
    }
    catch (Exception $e) {
        die("<p>Server error! Please contact the admin.</p>");
    }
?>

This creates a new address at the beginning of every new session, and stores it in the session variable.