Add documentation for GuzzleEventPublisher and CurlEventPublisher

Author: arun251

README.md

@@ -58,23 +58,40 @@ Require Guzzle as a dependency:
 
 It will then be used as the default way of fetching flags.
 
-With Guzzle, you could persist your cache somewhere other than the default in-memory store, like Memcached or Redis.  You could then specify your cache when initializing the client with the [cache option](https://github.com/launchdarkly/php-client/blob/master/src/LaunchDarkly/LDClient.php#L42).
+With Guzzle, you could persist your cache somewhere other than the default in-memory store, like Memcached or Redis.  You could then specify your cache when initializing the client with the [cache option](https://github.com/launchdarkly/php-client/blob/master/src/LaunchDarkly/LDClient.php#L44).
 
     $client = new LaunchDarkly\LDClient("YOUR_SDK_KEY", array("cache" => $cacheStorage));
 
 
 Using LD-Relay
 ==============
 
-* Setup [ld-relay](https://github.com/launchdarkly/ld-relay) in [daemon-mode](https://github.com/launchdarkly/ld-relay#redis-storage-and-daemon-mode) with Redis
+The LaunchDarkly Relay Proxy ([ld-relay](https://github.com/launchdarkly/ld-relay)) consumes the LaunchDarkly streaming API and can update
+a Redis cache operating in your production environment. The ld-relay offers many benefits such as performance and feature flag consistency. With PHP applications, we strongly recommend setting up ld-relay with a Redis store.
 
-* Require Predis as a dependency:
+1. Set up ld-relay in [daemon-mode](https://github.com/launchdarkly/ld-relay#redis-storage-and-daemon-mode) with Redis
 
-    php composer.phar require "predis/predis:1.0.*"
+2. Require Predis as a dependency:
 
-* Create the LDClient with the Redis feature requester as an option:
+        php composer.phar require "predis/predis:1.0.*"
 
-    $client = new LaunchDarkly\LDClient("your_sdk_key", ['feature_requester_class' => 'LaunchDarkly\LDDFeatureRequester', 'redis_host' => 'your.redis.host', 'redis_port' => 6379]);
+3. Create the LDClient with the Redis feature requester as an option:
+
+        $client = new LaunchDarkly\LDClient("your_sdk_key", [
+            'feature_requester_class' => 'LaunchDarkly\LDDFeatureRequester',
+            'redis_host' => 'your.redis.host',
+            'redis_port' => 6379
+        ]);
+
+4. If ld-relay is configured for [event forwarding](https://github.com/launchdarkly/ld-relay#event-forwarding), you can configure the LDClient to publish events to ld-relay instead of directly to `events.launchdarkly.com`. Using `GuzzleEventPublisher` with ld-relay event forwarding can be an efficient alternative to the default `curl`-based event publishing.
+
+        $client = new LaunchDarkly\LDClient("your_sdk_key", [
+            'event_publisher_class' => 'LaunchDarkly\GuzzleEventPublisher',
+            'events_uri' => 'http://your-ldrelay-host:8030',
+            'feature_requester_class' => 'LaunchDarkly\LDDFeatureRequester',
+            'redis_host' => 'your.redis.host',
+            'redis_port' => 6379
+        ]);
 
 Testing
 -------

composer.json

@@ -27,7 +27,7 @@
         "zendframework/zend-serializer": "^2.7"
     },
     "suggest": {
-        "guzzlehttp/guzzle": "(^6.2.1) Required when using RelayEventPublisher or the default FeatureRequester",
+        "guzzlehttp/guzzle": "(^6.2.1) Required when using GuzzleEventPublisher or the default FeatureRequester",
         "kevinrob/guzzle-cache-middleware": "(^1.4.1) Recommended for performance when using the default FeatureRequester",
         "predis/predis": "(^1.0) Required when using LDDFeatureRequester"
     },

src/LaunchDarkly/CurlEventPublisher.php

@@ -1,6 +1,16 @@
 <?php
 namespace LaunchDarkly;
 
+/**
+ * Sends events to the LaunchDarkly service using the `curl` command line tool.
+ * The `curl` requests are executed as background processes in order to
+ * minimize overhead to the PHP request. This `EventPublisher` implementation
+ * is the default for `LDClient`.
+ *
+ * `curl` must be installed in the environment's search path, or otherwise the
+ * absolute path to the executable must be specified using the `'curl'` option
+ * for `LDClient`.
+ */
 class CurlEventPublisher implements EventPublisher
 {
     private $_sdkKey;

src/LaunchDarkly/EventPublisher.php

@@ -1,6 +1,9 @@
 <?php
 namespace LaunchDarkly;
 
+/**
+ * Provides a transport mechanism for sending events to the LaunchDarkly service.
+ */
 interface EventPublisher {
     /**
      * @param string $sdkKey The SDK key for your account

src/LaunchDarkly/RelayEventPublisher.php renamed to src/LaunchDarkly/GuzzleEventPublisher.php

@@ -4,7 +4,17 @@
 use GuzzleHttp\Client;
 use Psr\Log\LoggerInterface;
 
-class RelayEventPublisher implements EventPublisher
+/**
+ * Sends events to the LaunchDarkly service using the GuzzleHttp client.
+ * This `EventPublisher` implement provides an in-process alternative to
+ * the default `CurlEventPublisher` implementation which forks processes.
+ *
+ * Note that this implementation executes synchronously in the request
+ * handler. In order to minimize request overhead, we recommend that you
+ * set up `ld-relay` in your production environment and configure the
+ * `events_uri` option for `LDClient` to publish to `ld-relay`.
+ */
+class GuzzleEventPublisher implements EventPublisher
 {
     /** @var string */
     private $_sdkKey;
@@ -45,7 +55,7 @@ public function publish($payload) {
 
             return $response->getStatusCode() < 300;
         } catch (\Exception $e) {
-            $this->_logger->warning("RelayEventPublisher::publish caught $e");
+            $this->_logger->warning("GuzzleEventPublisher::publish caught $e");
             return false;
         }
     }