[doc] add docs

Author: makasim

docs/client/message_bus.md

@@ -0,0 +1,16 @@
+# Client. Message bus
+ 
+Here's a description of message bus from [Enterprise Integration Patterns](http://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageBus.html)
+
+> A Message Bus is a combination of a common data model, a common command set, and a messaging infrastructure to allow different systems to communicate through a shared set of interfaces.
+
+If all your applications built on top of Enqueue Client you have to only make sure they send message to a shared topic. 
+The rest is done under the hood.
+
+If you'd like to connect another application (written on Python for example ) you have to follow these rules:
+
+* An application defines its own queue that is connected to the topic as fanout. 
+* A message sent to message bus topic must have a header `enqueue.topic_name`. 
+* Once a message is received it could be routed internally. `enqueue.topic_name` header could be used for that.
+
+[back to index](../index.md)

docs/client/message_examples.md

@@ -0,0 +1,78 @@
+# Client. Message examples
+ 
+## Delay 
+
+Message sent with a delay set is processed after the delay time exceed.
+Some brokers may not support it from scratch. 
+In order to use delay feature with [RabbitMQ](https://www.rabbitmq.com/) you have to install a [delay plugin](https://github.com/rabbitmq/rabbitmq-delayed-message-exchange).
+
+```php
+<?php
+
+use Enqueue\Client\Message;
+
+$message = new Message();
+$message->setDelay(60); // seconds
+
+/** @var \Enqueue\Client\MessageProducerInterface $producer */
+$producer->send('aTopic', $message);
+```
+
+## Expiration (TTL)
+
+The message may have an expiration or TTL (time to live). 
+The message is removed from the queue if the expiration exceeded but the message has not been consumed.
+For example it make sense to send a forgot password email within first few minutes, nobody needs it in an hour.
+
+```php
+<?php
+
+use Enqueue\Client\Message;
+
+$message = new Message();
+$message->setExpire(60); // seconds
+
+/** @var \Enqueue\Client\MessageProducerInterface $producer */
+$producer->send('aTopic', $message);
+```
+
+## Priority 
+
+You can set a priority If you want a message to be processed quicker than other messages in the queue.
+Client defines five priority constants: `MessagePriority::VERY_LOW`, `MessagePriority::LOW`, `MessagePriority::NORMAL`, `MessagePriority::HIGH`, `MessagePriority::VERY_HIGH`.
+The `MessagePriority::NORMAL` is default priority.
+
+```php
+<?php
+
+use Enqueue\Client\Message;
+use Enqueue\Client\MessagePriority;
+
+$message = new Message();
+$message->setPriority(MessagePriority::HIGH);
+
+/** @var \Enqueue\Client\MessageProducerInterface $producer */
+$producer->send('aTopic', $message);
+```
+
+## Timestamp, Content type, Message id
+
+Those are self describing things. 
+Usually they are set by Client so you dont have to worry about them. 
+If you do not like what Client set you can always set custom values:
+ 
+```php
+<?php
+
+use Enqueue\Client\Message;
+
+$message = new Message();
+$message->setMessageId('aCustomMessageId');
+$message->setTimestamp(time());
+$message->setContentType('text/plain');
+
+/** @var \Enqueue\Client\MessageProducerInterface $producer */
+$producer->send('aTopic', $message);
+```
+
+[back to index](../index.md)

docs/client/supported_brokers.md

@@ -0,0 +1,17 @@
+# Client. Supported brokers
+
+Here's the list of protocols and Client features supported by them 
+
+| Protocol       | Priority | Delay    | Expiration | Setup broker | Message bus |
+|:--------------:|:--------:|:--------:|:----------:|:------------:|:-----------:|
+| AMQP           |   No     |    No    |    Yes     |     Yes      |     Yes     |        
+| RabbitMQ AMQP  |   Yes    |    Yes*  |    Yes     |     Yes      |     Yes     |
+| STOMP          |   No     |    No    |    Yes     |     No       |     Yes**   |
+| RabbitMQ STOMP |   Yes    |    Yes*  |    Yes     |     Yes***   |     Yes**   |
+
+
+* \* Possible if a RabbitMQ delay plugin is installed.
+* \*\* Possible if topics (exchanges) are configured on broker side manually.
+* \*\*\* Possible if RabbitMQ Managment Plugin is installed.
+
+[back to index](../index.md)

docs/index.md

@@ -7,6 +7,13 @@
     - [NULL](null_transport.md)
 * Consumption
     - [Extensions](consumption/extensions.md)
+* Client
+    - [Message examples](client/message_examples.md)
+    - [Supported brokers](client/supported_brokers.md)
+    - [Message bus](client/message_bus.md)
+* Job queue
+    - [Run unique job](job_queue/run_unique_job.md)
+    - [Run sub job(s)](job_queue/run_sub_job.md)
 * EnqueueBundle (Symfony).  
     - [Quick tour](bundle/quick_tour.md)
     - [Config reference](bundle/config_reference.md)

docs/job_queue/run_sub_job.md

@@ -0,0 +1,63 @@
+## Job queue. Run sub job
+
+It shows how you can create and run a sub job, which it is executed separately. 
+You can create as many sub jobs as you like. 
+They will be executed in parallel. 
+
+```php
+<?php
+use Enqueue\Consumption\MessageProcessorInterface;
+use Enqueue\Client\MessageProducerInterface;
+use Enqueue\Consumption\Result;
+use Enqueue\Psr\Message;
+use Enqueue\Psr\Context;
+use Enqueue\JobQueue\JobRunner;
+use Enqueue\JobQueue\Job;
+use Enqueue\Util\JSON;
+
+class RootJobMessageProcessor implements MessageProcessorInterface
+{
+    /** @var JobRunner */
+    private $jobRunner;
+    
+    /** @var  MessageProducerInterface */
+    private $producer;
+
+    public function process(Message $message, Context $context)
+    {
+        $result = $this->jobRunner->runUnique($message->getMessageId(), 'aJobName', function (JobRunner $runner) {
+            $runner->createDelayed('aSubJobName1', function (JobRunner $runner, Job $childJob) {
+                $this->producer->send('aJobTopic', [
+                    'jobId' => $childJob->getId(),
+                    // other data required by sub job
+                ]);
+            });
+
+            return true;
+        });
+
+        return $result ? Result::ACK : Result::REJECT;
+    }
+}
+
+class SubJobMessageProcessor implements MessageProcessorInterface
+{
+    /** @var JobRunner */
+    private $jobRunner;
+
+    public function process(Message $message, Context $context)
+    {
+        $data = JSON::decode($message->getBody());
+
+        $result = $this->jobRunner->runDelayed($data['jobId'], function () use ($data) {
+            // do your job
+
+            return true;
+        });
+
+        return $result ? Result::ACK : Result::REJECT;
+    }
+}
+```
+
+[back to index](../index.md)

docs/job_queue/run_unique_job.md

@@ -0,0 +1,39 @@
+## Job queue. Run unique job
+
+There is job queue component build on top of a transport. It provides some additional features:
+
+* Stores jobs to a database. So you can query that information and build a UI for it.
+* Run unique job feature. If used guarantee that there is not any job with the same name running same time.
+* Sub jobs. If used allow split a big job into smaller pieces and process them asynchronously and in parallel.
+* Depended job. If used allow send a message when the whole job is finished (including sub jobs).
+  
+Here's some  examples.
+It shows how you can run unique job using job queue (The configuration is described in a dedicated chapter). 
+
+```php
+<?php 
+use Enqueue\Consumption\MessageProcessorInterface;
+use Enqueue\Consumption\Result;
+use Enqueue\Psr\Message;
+use Enqueue\Psr\Context;
+use Enqueue\JobQueue\JobRunner;
+
+class MessageProcessor implements MessageProcessorInterface
+{
+    /** @var JobRunner */
+    private $jobRunner;
+
+    public function process(Message $message, Context $context)
+    {
+        $result = $this->jobRunner->runUnique($message->getMessageId(), 'aJobName', function () {
+            // do your job, there is no any other processes executing same job,
+
+            return true; // if you want to ACK message or false to REJECT
+        });
+
+        return $result ? Result::ACK : Result::REJECT;
+    }
+}
+```
+
+[back to index](../index.md)

docs/quick_tour.md

@@ -156,11 +156,12 @@ $queueConsumer->consume();
 
 ## Client
 
-It provides a high level abstraction.
-The goal of the component is hide as much as possible details from you so you can concentrate on things that really matters. 
-For example, It configure a broker for you, if needed.
-It provides easy to use services for producing and processing messages.
-It supports message bus so different applications can send message to each other.
+It provides an easy to use high level abstraction.
+The goal of the component is hide as much as possible low level details so you can concentrate on things that really matters. 
+For example, It configure a broker for you by creating queuest, exchanges and bind them.
+It provides easy to use services for producing and processing messages. 
+It supports unified format for setting message expiration, delay, timestamp, correlation id.
+It supports message bus so different applications can talk to each other.
 
 Here's an example of how you can send and consume messages.
 
@@ -185,104 +186,6 @@ $client->send('foo_topic', 'Hello there!');
 $client->consume();
 ```
 
-## Job queue
-
-There is job queue component build on top of a transport. It provides some additional features:
-
-* Stores jobs to a database. So you can query that information and build a UI for it.
-* Run unique job feature. If used guarantee that there is not any job with the same name running same time.
-* Sub jobs. If used allow split a big job into smaller pieces and process them asynchronously and in parallel.
-* Depended job. If used allow send a message when the whole job is finished (including sub jobs).
-  
-Here's some  examples.
-First shows how you can run unique job using job queue (The configuration is described in a dedicated chapter). 
-
-```php
-<?php 
-use Enqueue\Consumption\MessageProcessorInterface;
-use Enqueue\Consumption\Result;
-use Enqueue\Psr\Message;
-use Enqueue\Psr\Context;
-use Enqueue\JobQueue\JobRunner;
-
-class MessageProcessor implements MessageProcessorInterface
-{
-    /** @var JobRunner */
-    private $jobRunner;
-
-    public function process(Message $message, Context $context)
-    {
-        $result = $this->jobRunner->runUnique($message->getMessageId(), 'aJobName', function () {
-            // do your job, there is no any other processes executing same job,
-
-            return true; // if you want to ACK message or false to REJECT
-        });
-
-        return $result ? Result::ACK : Result::REJECT;
-    }
-}
-```
-
-Second shows how you can create and run a sub job, which it is executed separately. 
-You can create as many sub jobs as you like. 
-They will be executed in parallel. 
-
-```php
-<?php
-use Enqueue\Consumption\MessageProcessorInterface;
-use Enqueue\Client\MessageProducerInterface;
-use Enqueue\Consumption\Result;
-use Enqueue\Psr\Message;
-use Enqueue\Psr\Context;
-use Enqueue\JobQueue\JobRunner;
-use Enqueue\JobQueue\Job;
-use Enqueue\Util\JSON;
-
-class RootJobMessageProcessor implements MessageProcessorInterface
-{
-    /** @var JobRunner */
-    private $jobRunner;
-    
-    /** @var  MessageProducerInterface */
-    private $producer;
-
-    public function process(Message $message, Context $context)
-    {
-        $result = $this->jobRunner->runUnique($message->getMessageId(), 'aJobName', function (JobRunner $runner) {
-            $runner->createDelayed('aSubJobName1', function (JobRunner $runner, Job $childJob) {
-                $this->producer->send('aJobTopic', [
-                    'jobId' => $childJob->getId(),
-                    // other data required by sub job
-                ]);
-            });
-
-            return true;
-        });
-
-        return $result ? Result::ACK : Result::REJECT;
-    }
-}
-
-class SubJobMessageProcessor implements MessageProcessorInterface
-{
-    /** @var JobRunner */
-    private $jobRunner;
-
-    public function process(Message $message, Context $context)
-    {
-        $data = JSON::decode($message->getBody());
-
-        $result = $this->jobRunner->runDelayed($data['jobId'], function () use ($data) {
-            // do your job
-
-            return true;
-        });
-
-        return $result ? Result::ACK : Result::REJECT;
-    }
-}
-```
-
 ## Cli commands
 
 The library provides handy commands out of the box.