Updated the documentation for 0.4

autoload.php

@@ -0,0 +1,15 @@
+<?php
+/* 
+ * You can include this file and it will handle registering the
+ * autoloaders.
+ */
+$autoloaders = spl_autoload_functions();
+if (!is_array($autoloaders) || !array_key_exists('Aerospike\\Bytes', $autoloaders)) {
+    spl_autoload_register(function ($class_name) {
+        if ($class_name == 'Aerospike\Bytes') {
+            require __DIR__. '/src/Bytes.php';
+        }
+    });
+}
+
+?>

doc/README.md

@@ -12,7 +12,7 @@ document gives further details on how data is organized in the cluster.
 
 ## Client API
 The Aerospike client for HHVM will eventually implement the full API
-described in the 
+described in the
 [aerospike/aerospike-client-php](https://github.com/aerospike/aerospike-client-php/blob/master/doc/README.md)
 repository. Currently a subset of the API has been implemented by the HNI
 extension.
@@ -22,24 +22,17 @@ extension.
 ### [Lifecycle and Connection Methods](apiref_connection.md)
 ### [Error Handling Methods](apiref_error.md)
 ### [Key-Value Methods](apiref_kv.md)
+### [Query and Scan Methods](apiref_streams.md)
 
 ## Implementation Status
 So far the *Runtime Configuration*, *Lifecycle and Connection Methods*, *Error*
 *Handling and Logging Methods*, and *Key-Value Methods* have been implemented.
 
-We have run into a problem implementing methods which include callbacks, such as
-[scan()](https://github.com/aerospike/aerospike-client-php/blob/master/doc/aerospike_scan.md)
-and [query()](https://github.com/aerospike/aerospike-client-php/blob/master/doc/aerospike_query.md).
-These seem to trigger a segfault. Consequently, we opened
-[issue 5527](https://github.com/facebook/hhvm/issues/5527)
-with the HHVM github repository. The current workaround is to run HHVM with its
-JIT disabled when such a segfault is encountered (`hhvm -v Eval.Jit=0 `).
-
 ## Persistent Connections
 
 Initializing the C-client to connect to a specified cluster is a costly
 operation, so ideally the C-client should be reused for the multiple requests
-made against the same PHP process (as is the case for mod_php and fastCGI).
+made against the same PHP process (as is the case for mod\_php and fastCGI).
 
 The PHP developer can determine whether the Aerospike class constructor will
 use persistent connections or not by way of an optional boolean argument.
@@ -72,30 +65,33 @@ distinguish them. This allows the serializer to behave in the correct manner.
 ### Example:
 
 ```php
+require('autoload.php');
 $client = new Aerospike(['hosts'=>[['addr'=>'127.0.0.1', 'port'=>3000]]]);
 
-$wrapped = new stdClass();
-$wrapped->s = "trunc\0ated";
+$str = 'Glagnar\'s Human Rinds, "It\'s a bunch\'a munch\'a crunch\'a human!';
+$deflated = new \Aerospike\Bytes(gzdeflate($str));
+$wrapped = new \Aerospike\Bytes("trunc\0ated");
 
 $key = $client->initKey('test', 'demo', 'wrapped-bytes');
-$status = $client->put($key, ['unwrapped'=>"trunc\0ated", 'wrapped'=> $wrapped]);
+$status = $client->put($key, ['unwrapped'=>"trunc\0ated", 'wrapped'=> $wrapped, 'deflated' => $deflated]);
 if ($status !== Aerospike::OK) {
     die($client->error());
 }
 $client->get($key, $record);
-var_dump($record);
-$wrapped = $record['bins']['wrapped'];
-$wrapped = $wrapped->s;
+$wrapped = \Aerospike\Bytes::unwrap($record['bins']['wrapped']);
+$deflated = $record['bins']['deflated'];
+$inflated = gzinflate($deflated->s);
+echo "$inflated\n";
 echo "wrapped binary-string: ";
 var_dump($wrapped);
 $unwrapped = $record['bins']['unwrapped'];
 echo "The binary-string that was given to put() without a wrapper: $unwrapped\n";
-echo "The binary-string that was given to put() without a wrapper: $unwrapped\n";
 
 $client->close();
 ```
 Outputs:
 ```
+Glagnar's Human Rinds, "It's a bunch'a munch'a crunch'a human!
 wrapped binary-string: string(10) "truncated"
 The binary-string that was given to put() without a wrapper: trunc
 ```

doc/aerospike.md

@@ -42,12 +42,22 @@ class Aerospike
     const POLICY_COMMIT_LEVEL_ALL;    // return success after committing all replicas (default)
     const POLICY_COMMIT_LEVEL_MASTER; // return success after committing the master replica
 
+    // OPT_SCAN_PRIORITY can be set to one of the following:
+    const SCAN_PRIORITY_AUTO;   //The cluster will auto adjust the scan priority
+    const SCAN_PRIORITY_LOW;    //Low priority scan.
+    const SCAN_PRIORITY_MEDIUM; //Medium priority scan.
+    const SCAN_PRIORITY_HIGH;   //High priority scan.
+
     // Options can be assigned values that modify default behavior
     const OPT_CONNECT_TIMEOUT;    // value in milliseconds, default: 1000
     const OPT_READ_TIMEOUT;       // value in milliseconds, default: 1000
     const OPT_WRITE_TIMEOUT;      // value in milliseconds, default: 1000
     const OPT_POLICY_RETRY;       // set to a Aerospike::POLICY_RETRY_* value
     const OPT_POLICY_EXISTS;      // set to a Aerospike::POLICY_EXISTS_* value
+    const OPT_SCAN_PRIORITY;      // set to a Aerospike::SCAN_PRIORITY_* value
+    const OPT_SCAN_PERCENTAGE;    // integer value 1-100, default: 100
+    const OPT_SCAN_CONCURRENTLY;  // boolean value, default: false
+    const OPT_SCAN_NOBINS;        // boolean value, default: false
     const OPT_POLICY_KEY;         // records store the digest unique ID, optionally also its (ns,set,key) inputs
     const OPT_POLICY_GEN;         // set to array( Aerospike::POLICY_GEN_* [, $gen_value ] )
     const OPT_POLICY_REPLICA;     // set to one of Aerospike::POLICY_REPLICA_*
@@ -141,13 +151,21 @@ class Aerospike
     // batch operation methods
     public int getMany ( array $keys, array &$records [, array $filter [, array $options]] )
     public int existsMany ( array $keys, array &$metadata [, array $options ] )
+
+    // query and scan methods
+    public int scan ( string $ns, string $set, callback $record_cb [, array $select [, array $options ]] )
 }
 ```
 
 ### [Runtime Configuration](aerospike_config.md)
 ### [Lifecycle and Connection Methods](apiref_connection.md)
 ### [Error Handling and Logging Methods](apiref_error.md)
 ### [Key-Value Methods](apiref_kv.md)
+### [Query and Scan Methods](apiref_streams.md)
 
 An overview of the development of the client is at the top level
 [README](README.md).
+
+We are working toward implementing the complete PHP client API. For comparison,
+here is the [Aerospike class](https://github.com/aerospike/aerospike-client-php/blob/master/doc/aerospike.md)
+as it exists on [aerospike/aerospike-client-php](https://github.com/aerospike/aerospike-client-php).

doc/aerospike_put.md

@@ -20,13 +20,13 @@ array keys and values. This behavior can be modified using the
 **Note:** a binary-string which includes a null-byte will get truncated at the
 position of the **\0** character if it is not wrapped. For more information and
 the workaround see
-[Handling Unsupported Types](https://github.com/aerospike/aerospike-client-php/blob/master/doc/README.md#handling-unsupported-types).
+[Handling Unsupported Types](https://github.com/aerospike/aerospike-client-hhvm/blob/master/doc/README.md#handling-unsupported-types).
 
 ## Parameters
 
 **key** the key under which to store the record. An array with keys ['ns','set','key'] or ['ns','set','digest'].
 
-**bins** the array of bin names and values to write. **Bin names cannot be longer than 14 characters.** Binary data containing the null byte (**\0**) may get truncated. See the [README](https://github.com/aerospike/aerospike-client-php/blob/master/doc/README.md#handling-unsupported-types) for more details and a workaround.
+**bins** the array of bin names and values to write. **Bin names cannot be longer than 14 characters.** Binary data containing the null byte (**\0**) may get truncated. See the [README](https://github.com/aerospike/aerospike-client-hhvm/blob/master/doc/README.md#handling-unsupported-types) for more details and a workaround.
 
 **ttl** the [time-to-live](http://www.aerospike.com/docs/client/c/usage/kvs/write.html#change-record-time-to-live-ttl) in seconds for the record.
 

doc/apiref_streams.md

@@ -0,0 +1,8 @@
+
+# Query and Scan Methods
+
+### [Aerospike::scan](aerospike_scan.md)
+```
+public int Aerospike::scan ( string $ns, string $set, callback $record_cb [, array $select [, array $options ]] )
+```
+

examples/scan_examples/README.md

@@ -1,16 +1,12 @@
 # Scan Method Examples
 
-There is a known HHVM bug ([issue 5527](https://github.com/facebook/hhvm/issues/5527)
-which causes the scan examples to segfault when the HHVM JIT is on. These
-examples **will** work if you run hhvm with the JIT turned off.
-
 ### Simple Scan
 `standard.php` shows how a callback method is invoked for each
 record streamed from the server as it is scans the _users_ set of the _test_
 namespace.
 
 ```bash
-hhvm  -v Eval.Jit=0 standard.php --host=192.168.119.3 -a -c
+hhvm standard.php --host=192.168.119.3 -a -c
 ```
 
 ### Buffering Results With a Limit
@@ -19,17 +15,6 @@ buffered into a _$result_ array, with the scan halted by returning `false` once
 a predetermined limit is reached.
 
 ```bash
-hhvm  -v Eval.Jit=0 buffered.php --host=192.168.119.3 -a -c
+hhvm buffered.php --host=192.168.119.3 -a -c
 ```
 
-### Scan Applying a UDF in the Background
-`background.php` shows how a UDF is applied to each record of a background scan
-of a set _users_ set in namespace _test_, transforming the value in the _age_ bin
-of those records.
-
-After checking the scan info to see whether it has completed, the transformed
-records are displayed.
-
-```bash
-hhvm  -v Eval.Jit=0 background.php --host=192.168.119.3 -a -c
-```

src/Bytes.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * Copyright 2013-2015 Aerospike, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @category   Database
+ * @author     Ronen Botzer <[email protected]>
+ * @copyright  Copyright 2013-2015 Aerospike, Inc.
+ * @license    http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2
+ * @link       https://github.com/aerospike/aerospike-client-php/blob/master/doc/README.md#handling-unsupported-types
+ * @filesource
+ */
+
+namespace Aerospike;
+
+/**
+ * \Aerospike\Bytes is a utility for wrapping PHP strings containing
+ * potentially harmful bytes such as \0. By wrapping the binary-string, the
+ * Aerospike client will serialize the data into an as_bytes rather than an
+ * as_string.
+ * This ensures that the string will not get truncated or otherwise lose data.
+ * The main difference is that strings in the Aerospike cluster can have a
+ * secondary index built over them, and queries executed against the index,
+ * while bytes data cannot.
+ *
+ * @package    Aerospike
+ * @subpackage Bytes
+ * @author     Ronen Botzer <[email protected]>
+ */
+class Bytes implements \Serializable
+{
+    /**
+     * The container for the binary-string
+     * @var string
+     */
+    public $s;
+
+    /**
+     * Constructor for \Aerospike\Bytes class.
+     *
+     * @param string $bin_str a PHP binary-string such as gzdeflate() produces.
+     */
+    public function __construct($bin_str) {
+        $this->s = $bin_str;
+    }
+
+    /**
+     * Returns a serialized representation of the binary-string.
+     * Called by serialize()
+     *
+     * @return string
+     */
+    public function serialize() {
+        return $this->s;
+    }
+
+    /**
+     * Re-wraps the binary-string when called by unserialize().
+     *
+     * @param string $bin_str a PHP binary-string. Called by unserialize().
+     */
+    public function unserialize($bin_str) {
+        return $this->s = $bin_str;
+    }
+
+    /**
+     * Returns the binary-string held in the \Aerospike\Bytes object.
+     *
+     * @return string
+     */
+    public function __toString() {
+        return $this->s;
+    }
+
+    /**
+     * Unwraps an \Aerospike\Bytes object, returning the binary-string inside.
+     *
+     * @param \Aerospike\Bytes $bytes_wrap
+     * @return string
+     */
+    public static function unwrap(\Aerospike\Bytes $bytes_wrap) {
+        return $bytes_wrap->s;
+    }
+
+}