From b3da0e764eb7f7496883ca3b5e8d0ac51b12f3f7 Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Sat, 5 Aug 2017 18:00:24 +0200
Subject: [PATCH] Add usage instructions to README

---
 README.md     | 26 ++++++++++++++++++++++++++
 composer.json |  2 +-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b93e71f..6898a20 100644
--- a/README.md
+++ b/README.md
@@ -11,3 +11,29 @@
 ```bash
 composer require kelunik/rate-limit
 ```
+
+## Usage
+
+You're in full control of any actions when the rate limit is exceeded. You can also already warn the user before he exceeds the limit.
+
+```php
+$current = yield $this->rateLimit->increment("{$userId}:{$action}");
+
+if ($current > $this->rateLimit) {
+    // show captcha or error page or do anything you want
+} else {
+    // request is within the limit, continue normally
+}
+```
+
+If you want to expose the limits, e.g. in an HTTP API, you can also request the reset time for a given key.
+
+```php
+$current = yield $this->rateLimit->increment("{$userId}:{$action}");
+
+$response->setHeader("x-ratelimit-limit", "100");
+$response->setHeader("x-ratelimit-remaining", $current);
+$response->setHeader("x-ratelimit-reset", yield $this->rateLimit->ttl("{$userId}:{$action}"));
+```
+
+`RateLimit::ttl()` returns the seconds until the limit is reset. If you want to return the absolute time, you can just add `time()` to that value.
diff --git a/composer.json b/composer.json
index 45176c3..03577ec 100644
--- a/composer.json
+++ b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "kelunik/rate-limit",
-    "description": "Asynchronous Rate Limits.",
+    "description": "Rate Limiting for Amp.",
     "license": "MIT",
     "keywords": [
         "amp",