<commit_before>#Burdette
A Rate-Limiting Library for PHP 5.4+
------------------------------------
[![Build Status](https://travis-ci.org/squinones/burdette.svg?branch=master)](https://travis-ci.org/squinones/burdette) [![Code Climate](https://codeclimate.com/github/squinones/burdette/badges/gpa.svg)](https://codeclimate.com/github/squinones/burdette) [![Test Coverage](https://codeclimate.com/github/squinones/burdette/badges/coverage.svg)](https://codeclimate.com/github/squinones/burdette)

###What does this do?
This library is primarily designed for APIs that wish to limit how many requests a client can make over a given period
of time. In theory it can be used to throttle any kind of behavior. If you find a neat use case, we'd love to hear 
about it!

###Check back soon
This is a new project! Check back soon for more information!
<commit_msg>Added usage information<commit_after>#Burdette
A Rate-Limiting Library for PHP 5.4+
------------------------------------
[![Build Status](https://travis-ci.org/squinones/burdette.svg?branch=master)](https://travis-ci.org/squinones/burdette) [![Code Climate](https://codeclimate.com/github/squinones/burdette/badges/gpa.svg)](https://codeclimate.com/github/squinones/burdette) [![Test Coverage](https://codeclimate.com/github/squinones/burdette/badges/coverage.svg)](https://codeclimate.com/github/squinones/burdette)

###What does this do?
This library is primarily designed for APIs that wish to limit how many requests a client can make over a given period
of time. In theory it can be used to throttle any kind of behavior. If you find a neat use case, we'd love to hear 
about it!

### Usage
At a basic level, you have a strategy, which is just a class that implements a specific rate-limiting policy. Strategies operate on buckets which maintain the state for any given identity. The bucket contains tokens which are replenished periodically. When a bucket has no more tokens to give, the identity has run up against the rate limit and should be stopped.

Let's use a practical example. Say you have an API endpoint /foo and you want to limit it so that any given IP address may only access /foo 1 time per hour.

In this case, the IP address is the identity. We'll employ a `TimeBlockStrategy` to implement the policy we want. Ignore the reference to a bucket repository for the moment. It will be explained later.
```php
use Burdette\Identities\StringIdentity;
use Burdette\Strategies\TimeBlockStrategy;

$identity = new StringIdentity($client_ip);
$strategy = new TimeBlockStrategy($bucket_repository);
$strategy->setReplenishmentRate(100, TimeBlockStrategy::HOURLY);

$token = $strategy->newToken($identity);
echo $token->isAllowed() . "\n";
echo $strategy->getNextReplenishmentTime();

$new_token = $strategy->newToken($identity);
echo $token->isAllowed() . "\n";
echo $strategy->getNextReplenishmentTime();
```

Running this code we should see something like...
```
true
Sat, 06 Dec 2014 22:00:00 -0500

false
Sat, 06 Dec 2014 22:00:00 -0500
```

###Check back soon
This is a new project! Check back soon for more information!

{'fraction_non_alphanumeric': 0.1273432449903038, 'fraction_numerical': 0.012928248222365869, 'mean_word_length': 4.477876106194691, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 10, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1105777', 'n_tokens_mistral': 952, 'n_tokens_neox': 899, 'n_words': 339}