Recommend this page to a friend! 
Classes of Christian Vigh  >  PHP Random.Org API  >  README.md  >  Download 

DownloadINTRODUCTIONThe RandomOrg class encapsulates access to the random.org web site (http://www.random.org). This site allows you to retrieve true random numbers, which are different from the ones returned by pseudorandom generators such as the builtin rand() and mt_rand() PHP functions. Pseudorandom generators are usually implemented by a distribution function with a formula that uses prime numbers. To sum up a little bit, if you call a pseudonumber generator function 100 times to return you a number between 1 and 100, then you will obtain numbers between 1 and 100, in an order that appears to be random. The seed (the initial value used for the computation of the first pseudorandom number) has a direct influence on the order of the results. Of course, as you might guess, you cannot obtain true random numbers from deterministic methods. I'm not aware of any pseudorandom number generator that could return you the same consecutive value more than once. Of course, these are handy methods that can help you to test your code with some "random" data, but they are subject to caution when talking about cryptography aspects or even password generators, because they are deterministic. This is where the random.org* website (and theRandomOrg PHP class) enter into action. The consecutive values that you will be able to retrieve from the site through this class have clearly no mathematical relashionship between them. They are simply random. HOW DOES IT WORKS ?The random.org site offers an API to freely retrieve random values, with quota restrictions. Data can be fetched by using one of the following methods :
The current version of the RandomOrg class uses the old API and does not require you to register on the site. RESTRICTIONSThe services offered by random.org are mostly free ; however, you must obey to a certain number of usage rules that are described here : https://www.random.org/clients/. To sum up :
Such restrictions may seem drastic, but remember it's a free service... WHAT IS THE ROLE OF THE RandomOrg CLASS ?In such a context, the RandomOrg class helps you to :
For the latter case, the RandomOrg class distinguishes between two types of requests :
Note that you cannot retrieve more than RandomOrg::MAX\_VALUES (10000) at once. REFERENCEQuota usageAll the methods retrieving random values affect your current quota ; the rules are the following :
METHODSCONSTRUCTOR
Instantiates an object for accessing the random.org site, using the specified user agent string for http accesses. If not specified, the value used for the user agent string will be that of the static variable RandomOrg::$GlobalUserAgent. It is highly recommended that you put your email address here, so that the random.org site can contact you in case of problems. Instantiating a RandomOrg object automatically retrieves your current quota from the site, that you can later get using the GetQuota() method. $array = $random > GetBytes ( $count )Retrieve a sequence of $count random bytes as an array. The $count parameter must be between 1 and RandomOrg::MAX_BYTE_VALUES. The total size of the request which will be deduced from your current quota is : $count 8 bits. $float = $random > GetFloat ( $decimal\_places = RandomOrg::MAX\_DECIMAL\_PLACES ) ;Retrieves one single floatingpoint value. You can specify the number of decimal places you want, up to RandomOrg::MAX\_DECIMAL\_PLACES (20). The returned value will be in the range 0..1, using the number of decimal places you specified. The total size of the request which will be deduced from your current quota is : 64 bits. IMPORTANT NOTE : This method is provided here only for convenience reasons, when all you need is one floatingpoint value. You mustn't use this method in a loop to retrieve values one by one. Should this be the case, use the GetFloats() method instead, specifying the number of values you really want to retrieve. $array = $random > GetFloats ( $count, $decimal_places = RandomOrg::MAX_DECIMAL_PLACES ) ;Retrieves $count floatingpoint values. You can specify the number of decimal places you want, up to RandomOrg::MAX\_DECIMAL\_PLACES (20). The method returns an array of floatingpoint values, in the range 0..1, using the number of decimal places you specified.. The total size of the request which will be deduced from your current quota is : count \* 64 bits. $integer = $random > GetInteger ( $min = RandomOrg::MIN\_INTEGER\_VALUE, $max = RandomOrg::MAX\_INTEGER\_VALUE ) ;Retrieves one single integer value. You can specify a range restriction for the $min and max parameters. By default, the returned value will be in the range RandomOrg::MIN\_INTEGER\_VALUE (1,000,000,000) and RandomOrg::MAX\_INTEGER\_VALUE (+1,000,000,000) The returned value will be in the range $min..$max. The total size of the request which will be deduced from your current quota is : 32 bits. IMPORTANT NOTE : This method is provided here only for convenience reasons, when all you need is one integer value. You mustn't use this method in a loop to retrieve values one by one. Should this be the case, use the GetIntegers() method instead, specifying the number of values you really want to retrieve. $array = $random > GetIntegers ( $count, $min = RandomOrg::MIN\_INTEGER\_VALUE, $max = RandomOrg::MAX\_INTEGER\_VALUE ) ;Retrieves $count integer values. You can specify a range restriction for the $min and max parameters. By default, the returned value will be in the range RandomOrg::MIN\_INTEGER\_VALUE (1,000,000,000) and RandomOrg::MAX\_INTEGER\_VALUE (+1,000,000,000). The method returns an array of integer values, in the range $min..$max. The total size of the request which will be deduced from your current quota is : $count \* 32 bits. $password = $random > GetPassword ( $length ) ;Retrieves one single random password of the specified length. The $length parameter must be between RandomOrg::MIN\_PASSWORD\_LENGTH (6) and RandomOrg::MAX\_PASSWORD\_LENGTH (20). This method is an alias for :
The total size of the request which will be deduced from your current quota is : $length \* 8 bits. IMPORTANT NOTE : This method is provided here only for convenience reasons, when all you need is one random password string value. You mustn't use this method in a loop to retrieve values one by one. Should this be the case, use the GetPasswords() method instead, specifying the number of values you really want to retrieve. $array = $random > GetPasswords ( $count, $length ) ;Retrieves $count random passwords of the specified length. The $length parameter must be between RandomOrg::MIN\_PASSWORD\_LENGTH (6) and RandomOrg::MAX\_PASSWORD\_LENGTH (20). This method is an alias for :
The total size of the request which will be deduced from your current quota is : $count \$length\ 8 bits. $quota = $random > GetQuota ( $current = true, $ip = null ) ;Retrieves your current quota, in bits. When the $current parameter is true, the method uses the last quota that the RandomOrg class has computed for you. When false, it will issue an http request to the random.org site to retrieve the actual quota. Note that issuing an http request for retrieving your quota does not affect your quota... $array = $random > GetSequence ( $min, $max ) ;Returns an array of integer values in the range $min..$max, arranged in a truly random order. The values $min and $max must be in the range RandomOrg::MIN\_INTEGER\_VALUE (1,000,000,000) and RandomOrg::MAX\_INTEGER\_VALUE (+1,000,000,000). The value $max  $min + 1 must not exceed RandomOrg::MAX\_SEQUENCE\_RANGE (10000). The total size of the request which will be deduced from your current quota is : ( $max  $min + 1 ) \* 32 bits. $string = $random > GetString ( $length, $options = RandomOrg::STRING\_ALPHA ) ;Retrieves a random string of length $length, using the generation options specified by the $options parameter (see the Constants section for a list of available options). The $length parameter must not exceed RandomOrg::MAX\_SRING\_LENGTH (20). The total size of the request which will be deduced from your current quota is : $length \* 8 bits. $array = $random > GetStrings ( $count, $length, $options = self::STRING\_ALPHA ) ;Retrieves an array of count random strings of length $length, using the generation options specified by the $options parameter (see the Constants section for a list of available options). The $length parameter must not exceed RandomOrg::MAX\_SRING\_LENGTH (20). The total size of the request which will be deduced from your current quota is : $count \$length\ 8 bits. Informational functionsThe set of methods described below provides you with information related to the last executed query. They all have a $global parameter which determines the level of information you want to retrieve :
$query = $random > GetQuery ( $global = false ) ;Returns the HTTP query that was built for the latest request that has been issued. $time = $random > GetQueryTime ( $global = false ) ;Returns the time where the last HTTP query was executed, as a Unix timestamp. $text = $random > GetResult ( $global = false ) ;Returns the raw text results obtained through the last HTTP request. $elapsed = $random > GetElapsed ( $global = false ) ;Returns the elapsed time, in milliseconds, of the last executed HTTP request. $time = $random > GetResultTime ( $global = false ) ;Returns the time where the results of the last HTTP request were received, as a Unix timestamp. $type = $random > GetType ( $global = false ) ;Returns the type of the last executed query ; it can be one of the following values :
$array = $random > GetQueryInfo ( $global = false ) ;This method is a combination of all of the above ; it returns an associative array with the following entries :
PROPERTIESThis class does not contain any public properties. CONSTANTSThe following constants are defined for enforcing the management of your daily quota :
The following constants specifies the limits for some HTTP requests :
The following constants give the limits on the number of values that can be retrieved in one shot :
The following set of bits can be specified for the $options parameter of the GetString() and *GetStrings() methods :
