Rename examples and update some comments.

[ci skip]

examples/CustomDistributionStrategy.php → examples/custom_cluster_distributor.php

@@ -9,11 +9,11 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
-// Developers can customize the distribution strategy used by the client
-// to distribute keys among a cluster of servers simply by creating a class
-// that implements Predis\Distribution\DistributorInterface.
+// Developers can implement Predis\Distribution\DistributorInterface to create
+// their own distributors used by the client to distribute keys among a cluster
+// of servers.
 
 use Predis\Connection\PredisCluster;
 use Predis\Cluster\Distributor\DistributorInterface;
@@ -43,7 +43,7 @@ public function remove($node) {
 
     public function get($key) {
         if (0 === $count = $this->nodesCount) {
-            throw new RuntimeException('No connections');
+            throw new RuntimeException('No connections.');
         }
 
         return $this->nodes[$count > 1 ? abs($key % $count) : 0];

examples/SimpleDebuggableConnection.php → examples/debuggable_connection.php

@@ -9,7 +9,12 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
+
+// This is an example of how you can easily extend an existing connection class
+// and trace the execution of commands for debugging purposes. This can be quite
+// useful as a starting poing to understand how your application interacts with
+// Redis.
 
 use Predis\Command\CommandInterface;
 use Predis\Connection\StreamConnection;

examples/DispatcherLoop.php → examples/dispatcher_loop.php

@@ -9,20 +9,18 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
-
-/*
-This is a basic example on how to use the Predis\DispatcherLoop class.
-
-To see this example in action you can just use redis-cli and publish some
-messages to the 'events' and 'control' channel, e.g.:
-
-./redis-cli
-PUBLISH events first
-PUBLISH events second
-PUBLISH events third
-PUBLISH control terminate_dispatcher
-*/
+require __DIR__.'/shared.php';
+
+// This is a basic example on how to use the Predis\DispatcherLoop class.
+//
+// To see this example in action you can just use redis-cli and publish some
+// messages to the 'events' and 'control' channel, e.g.:
+
+// ./redis-cli
+// PUBLISH events first
+// PUBLISH events second
+// PUBLISH events third
+// PUBLISH control terminate_dispatcher
 
 // Create a client and disable r/w timeout on the socket
 $client = new Predis\Client($single_server + array('read_write_timeout' => 0));

examples/SendingRedisCommands.php → examples/executing_redis_commands.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 $client = new Predis\Client($single_server);
 

examples/KeyPrefixes.php → examples/key_prefixing.php

@@ -9,13 +9,12 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
-// Predis ships with a KeyPrefixProcessor class that is used to transparently
-// prefix each key before sending commands to Redis, even for complex commands
-// such as SORT, ZUNIONSTORE and ZINTERSTORE. Key prefixes are useful to create
-// user-level namespaces for you keyspace, thus eliminating the need for separate
-// logical databases.
+// Predis can prefix keys found in commands arguments before sending commands to
+// Redis, even for complex commands such as SORT, ZUNIONSTORE and ZINTERSTORE.
+// Prefixing keys can be useful to create user-level namespaces for you keyspace
+// thus reducing the need for separate logical databases in certain scenarios.
 
 $client = new Predis\Client($single_server, array('prefix' => 'nrk:'));
 

examples/ServerSideScripting.php → examples/lua_scripting_abstraction.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 // This example will not work with versions of Redis < 2.6.
 //

examples/MonitorConsumer.php → examples/monitor_consumer.php

@@ -9,10 +9,10 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
-// This is a basic example on how to use the Predis\Monitor\Consumer class.
-// You can use redis-cli to send commands to the same Redis instance your client is
+// This is a basic example on how to use the Predis\Monitor\Consumer class. You
+// can use redis-cli to send commands to the same Redis instance your client is
 // connected to, and then type "ECHO QUIT_MONITOR" in redis-cli when you want to
 // exit the monitor loop and terminate this script in a graceful way.
 

examples/PipeliningCommands.php → examples/pipelining_commands.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 // When you have a whole set of consecutive commands to send to a redis server,
 // you can use a pipeline to dramatically improve performances. Pipelines can

examples/PubSubConsumer.php → examples/pubsub_consumer.php

@@ -9,10 +9,10 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
-// Redis 2.0 features new commands that allow clients to subscribe for
-// events published on certain channels (PUBSUB).
+// Starting from Redis 2.0 clients can subscribe and listen for events published
+// on certain channels using a Publish/Subscribe (PUB/SUB) approach.
 
 // Create a client and disable r/w timeout on the socket
 $client = new Predis\Client($single_server + array('read_write_timeout' => 0));

examples/RedisCollectionsIterators.php → examples/redis_collections_iterators.php

@@ -9,19 +9,22 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 use Predis\Collection\Iterator;
 
-// Redis 2.8 features new commands allowing clients to incrementally
-// iterate over collections without blocking the server like it happens
-// when a command such as KEYS is executed on a Redis instance storing
-// millions of keys. These commands are SCAN (iterates over the keyspace),
-// SSCAN (iterates over members of a set), ZSCAN (iterates over members
-// and ranks of a sorted set) and HSCAN (iterates over fields and values
-// of an hash). Predis provides a specialized abstraction for each command
-// based on SPL iterators making it possible to easily consume SCAN-based
-// iterations in your PHP code.
+// Starting from Redis 2.8, clients can iterate incrementally over collections
+// without blocking the server like it happens when a command such as KEYS is
+// executed on a Redis instance storing millions of keys. These commands are:
+//
+//   - SCAN (iterates over the keyspace)
+//   - SSCAN (iterates over members of a set)
+//   - ZSCAN (iterates over members and ranks of a sorted set)
+//   - HSCAN (iterates over fields and values of an hash).
+
+// Predis provides a specialized abstraction for each command based on standard
+// SPL iterators making it possible to easily consume SCAN-based iterations in
+// your PHP code.
 //
 // See https://redis.io/commands/scan for more details.
 //

examples/MasterSlaveReplicationComplex.php → examples/replication_complex.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 // Predis allows to set Lua scripts as read-only operations for replication.
 // This works for both EVAL and EVALSHA and also for the client-side abstraction

examples/MasterSlaveReplication.php → examples/replication_simple.php

@@ -9,16 +9,16 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
-// Predis supports master / slave replication scenarios where write operations are
-// performed on the master server and read operations are executed against one of
-// the slaves. The behaviour of commands or EVAL scripts can be customized at will.
-// As soon as a write operation is performed, all the subsequent requests (reads
-// or writes) will be served by the master server.
+// Predis supports master / slave replication scenarios where write operations
+// are performed on the master server and read operations are executed against
+// one of the slaves. The behavior of commands or EVAL scripts can be customized
+// at will. As soon as a write operation is performed the client switches to the
+// master server for all the subsequent requests (either reads and writes).
 //
-// This example must be executed with the second Redis server acting as the slave
-// of the first one using the SLAVEOF command.
+// This example must be executed using the second Redis server configured as the
+// slave of the first one (see the "SLAVEOF" command).
 //
 
 $parameters = array(

examples/session_handler.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the Predis package.
+ *
+ * (c) Daniele Alessandri <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.'/shared.php';
+
+// This example demonstrates how to use Predis to save PHP sessions on Redis.
+//
+// The value of `session.gc_maxlifetime` in `php.ini` will be used by default as
+// the TTL for keys holding session data but this value can be overridden when
+// creating the session handler instance using the `gc_maxlifetime` option.
+//
+// NOTE: this class requires PHP >= 5.4 but can be used on PHP 5.3 if a polyfill
+// for SessionHandlerInterface is provided either by you or an external package
+// like `symfony/http-foundation`.
+//
+// See https://www.php.net/class.sessionhandlerinterface.php for more details.
+//
+
+if (!interface_exists('SessionHandlerInterface')) {
+    die("ATTENTION: the session handler implemented by Predis requires PHP >= 5.4.0 ".
+        "or a polyfill for SessionHandlerInterface provided by an external package.\n");
+}
+
+// Instantiate a new client just like you would normally do. Using a prefix for
+// keys will effectively prefix all session keys with the specified string.
+$client = new Predis\Client($single_server, array('prefix' => 'sessions:'));
+
+// Set `gc_maxlifetime` to specify a time-to-live of 5 seconds for session keys.
+$handler = new Predis\Session\Handler($client, array('gc_maxlifetime' => 5));
+
+// Register the session handler.
+$handler->register();
+
+// We just set a fixed session ID only for the sake of our example.
+session_id('example_session_id');
+
+session_start();
+
+if (isset($_SESSION['foo'])) {
+    echo "Session has `foo` set to {$_SESSION['foo']}", PHP_EOL;
+} else {
+    $_SESSION['foo'] = $value = mt_rand();
+    echo "Empty session, `foo` has been set with $value", PHP_EOL;
+}

examples/TransactionWithCAS.php → examples/transaction_using_cas.php

@@ -9,7 +9,7 @@
  * file that was distributed with this source code.
  */
 
-require 'SharedConfigurations.php';
+require __DIR__.'/shared.php';
 
 // This is an implementation of an atomic client-side ZPOP using the support for
 // check-and-set (CAS) operations with MULTI/EXEC transactions, as described in