Docs

README.md

@@ -10,7 +10,7 @@
 Remember a visitor's original referer in session. The referer is (highest priority first):
 
 - The `utm_source` query parameter
-- The domain from the server's `HTTP_REFERER` if it's an external URL
+- The domain from the request's `Referer` header if there's an external host in the URL
 - Empty
 
 ## Postcardware
@@ -29,11 +29,93 @@ You can install the package via composer:
 composer require spatie/laravel-referer
 ```
 
+You'll need to register the service provider:
+
+```php
+// config/app.php
+
+'providers' => [
+    // ...
+    Spatie\Referer\RefererServiceProvider::class,
+];
+```
+
+You can optionally register the facade:
+
+```php
+// config/app.php
+
+'aliases' => [
+    // ...
+   'Referer' => Spatie\Referer\Facades\Referer::class,
+];
+```
+
+You can publish the config file with:
+
+```
+php artisan vendor:publish --provider="Spatie\Referer\RefererServiceProvider"
+```
+
+Publishing the config file is only necessary if you'd want to change the key in which the referer is stored in the session.
+
+```
+return [
+
+    /*
+     * The key that will be used to remember the referer in the session.
+     */
+    'key' => 'referer',
+
+];
+```
+
 ## Usage
 
-``` php
-$skeleton = new Spatie\Skeleton();
-echo $skeleton->echoPhrase('Hello, Spatie!');
+To capture the referer, all you need to do is add the `Spatie\Referer\CaptureReferer` middleware to your middleware stack. In most configuration's, you'll only want to capture the referer in "web" requests, so it makes sense to register it in the `web` stack. Make sure it comes **after** Laravel's `StartSession` middleware!
+
+```php
+// app/Http/Kernel.php
+
+protected $middlewareGroups = [
+    'web' => [
+        // ...
+        \Illuminate\Session\Middleware\StartSession::class,
+        // ...
+        \Spatie\Referer\CaptureReferer::class,
+        // ...
+    ],
+    // ...
+];
+```
+
+The easiest way to retrieve the referer is by using the facade:
+
+```php
+use Referer;
+
+$referer = Referer::get(); // 'google.com'
+```
+
+The captured referer is (from high to low priority):
+
+- The `utm_source` query parameter, or:
+- The domain from the request's `Referer` header if there's an external host in the URL, or:
+- Empty
+
+An empty referer will never overwrite an exisiting referer. So if a visitor comes from google.com and visits a few pages on your site, those pages won't affect the referer since local hosts are ignored.
+
+### Forgetting or manually setting the referer
+
+The `Referer` class provides dedicated methods to forget, or manually set the referer.
+
+```php
+use Referer;
+
+Referer::set('google.com');
+Referer::get(); // 'google.com'
+Referer::forget();
+Referer::get(); // ''
 ```
 
 ## Changelog
@@ -43,7 +125,7 @@ Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recen
 ## Testing
 
 ``` bash
-$ composer test
+composer test
 ```
 
 ## Contributing
@@ -60,6 +142,7 @@ If you discover any security related issues, please email freek@spatie.be instea
 - [All Contributors](../../contributors)
 
 ## About Spatie
+
 Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource).
 
 ## License