Merge pull request #66 from abdumu/master

add docs

docs/1_introduction.md

@@ -0,0 +1,19 @@
+---
+prev: ./
+next: 2_requirements
+---
+
+# Introduction
+Laravel Visits is a counter that can be attached to any model to track its visits with useful features like IP-protection and lists caching.
+
+
+
+
+## Features
+- A model item can have **many types** of recorded visits (using tags).
+- It's **not limited to one type of Model** (like some packages that allow only User model).
+- Record per visitor and not by vistis using IP detecting, so even with refresh, **a visit won't duplicate** (can be changed from config/visits.php). 
+- Get **Top/Lowest visited items** per a model.
+- Get most visited **countries, refs, OSes, and languages**.
+- Get **visits per a period of time** like a month of a year of an item or model.
+- Supports **multiple data engines**: Redis or database (any SQL engine that Eloquent supports). 

docs/2_requirements.md

@@ -0,0 +1,17 @@
+---
+prev: 1_introduction
+next: 3_installation
+---
+
+# Requirements
+- Laravel 5.5+
+- PHP 7.2+
+- Data engine (Redis or Database) 
+
+### Data Egnine options 
+You can choose to use Redis or database as your data engine from `config/visits.php`
+#### Redis
+Make sure that Redis is configured and ready. (see [Laravel Redis Configuration](https://laravel.com/docs/5.6/redis#configuration))
+#### (Eloquent) Database
+Laravel visits uses any database that Eloquent uses.
+

docs/3_installation.md

@@ -0,0 +1,118 @@
+---
+prev: 2_requirements
+next: 4_quick-start
+---
+
+# Installation
+
+To get started with Laravel Visits, use Composer to add the package to your project's dependencies:
+```bash
+composer require awssat/laravel-visits
+```
+
+
+## Configurations
+To adjust the package to your needs, you can publish the config file `config/visits.php` to your project's config folder using:
+
+```bash
+php artisan vendor:publish --provider="Awssat\Visits\VisitsServiceProvider" --tag=config
+```
+
+
+## Redis Configuration
+If you are not using Redis as your default data engine, skip this.
+
+By default `laravel-visits` doesn't use the default laravel redis configuration (see [issue #5](https://github.com/awssat/laravel-visits/issues/5))
+
+To prevent any data loss add a new connection in `config/database.php`
+
+```php
+'laravel-visits' => [
+    'host' => env('REDIS_HOST', '127.0.0.1'),
+    'password' => env('REDIS_PASSWORD', null),
+    'port' => env('REDIS_PORT', 6379),
+    'database' => 3, // anything from 1 to 15, except 0 (or what is set in default)
+],
+```
+
+and you can define your redis connection name in `config/visits.php`
+```php
+'connection' => 'laravel-visits'
+```
+
+## Eloquent (database) configuration
+If you are using Redis as your default data engine, skip this.
+
+Publish migration file, then migrate
+ ```sh
+php artisan vendor:publish --provider="Awssat\Visits\VisitsServiceProvider" --tag=migrations
+```
+ ```sh
+php artisan migrate
+```
+
+## Package Configuration
+Laravel Visits can be configured to act the way you like, `config/visits.php` is clear and easy to understand but here some explanation for its settings.
+
+### config/visits.php settings explained
+#### engine
+```php
+'engine' => 'redis',
+```
+Suported data engines are `redis`, and `eloquent` currently.
+If you use `eloquent` then data will be stored in the default database (MySQL, SQLite or the one you are using)
+
+#### connection
+```php
+'connection' => 'laravel-visits',
+```
+Currently only applies when using Redis as data engine. Check [Redis Configuration](#redis-configuration)
+
+#### periods
+```php
+'periods' => [
+    'day',
+    'week',
+    'month',
+    'year',
+],
+```
+By default, Visits of `day`, `week`, `month`, and `year` are recorded. But you can add or remove any of them as you like.
+> **Note** supported periods can be found in [periods-options](8_clear-and-reset-values.html#periods-options) 
+::: tip
+You can add `periods` to global_ignore setting to skip recording any of these periods. 
+:::
+
+#### keys_prefix
+```php
+'keys_prefix' =>  'visits',
+```
+A word that's appended to the begining of keys names. If you are using shared Redis database, it's important to keep this filled.
+
+#### remember_ip
+```php
+'remember_ip' => 15 * 60, // seconds
+```
+Every distinct IP will only be recorded as one visit every 15 min (default).
+
+#### always_fresh
+```php
+'always_fresh' => false,
+```
+If you set this to `true`, then any [Visits Lists](7_visits-lists) won't be cached any will return a new generated list.
+::: tip
+We don't recommend enabling this feature as it's not good for performance.
+:::
+
+#### ignore_crawlers
+```php
+'ignore_crawlers' => true,
+```
+By default, visits from search engines bots and any other recognizable bots are not recorded. By enabling this you allow visits from bots to be recoded.
+
+
+#### global_ignore
+```php
+'global_ignore' => [],
+```
+By default, 'country', 'refer', 'periods', 'operatingSystem', and 'language' of a visitor are recoded. You can disable recoding any of them by adding them to the list.

docs/4_quick-start.md

@@ -0,0 +1,72 @@
+---
+prev: 3_installation
+next: 5_increments-and-decrements
+---
+
+
+# Quick Start
+
+## Start using it
+It's simple.
+
+Using `visits` helper as:
+
+```php
+visits($model)->{method}()
+```
+Where:
+- **$model**: is any Eloquent model from your project.
+- **{method}**: any method that is supported by this library, and they are documented below.
+
+## Tags
+- You can track multiple kinds of visits to a single model using the tags as 
+```php
+visits($model,'tag1')->increment()
+```
+
+
+## Integration with any model
+
+You can add a `visits` method to your model class:
+
+```php
+class Post extends Model
+{
+
+    //....
+
+    public function vzt()
+    {
+        return visits($this);
+    }
+}
+```
+
+Then you can use it as:
+
+```php
+$post = Post::find(1);
+$post->vzt()->increment();
+$post->vzt()->count();
+```
+
+
+## Relationship with models (only for Eloquent engine)
+If you are using visits with eloquent as engine (from config/visits.php; engine => 'eloquent') then you can add a relationship method to your models.
+
+```php
+class Post extends Model
+{
+
+    //....
+
+    public function visits()
+    {
+        return visits($this)->relation();
+    }
+}
+
+//then:
+
+Post::with('visits')->get(); 
+```

docs/5_increments-and-decrements.md

@@ -0,0 +1,61 @@
+---
+prev: 4_quick-start
+next: 6_retrieve-visits-and-stats
+---
+
+
+# Increments and Decrements
+
+## Increment
+### One
+```php
+visits($post)->increment();
+```
+### More than one
+```php
+visits($post)->increment(10);
+```
+
+## Decrement
+### One
+```php
+visits($post)->decrement();
+```
+### More than one
+```php
+visits($post)->decrement(10);
+```
+
+
+
+::: tip Note
+Using Increment/decrement method will only work once every 15 minutes (default setting). You can use force methods or modifiy the time from settings or using seconds method.
+:::
+
+
+## Increment/decrement once per x seconds 
+based on visitor's IP
+```php
+visits($post)->seconds(30)->increment()
+```
+> **Note:** this will override default config setting (once each 15 minutes per IP).
+
+
+## Force increment/decrement
+```php
+visits($post)->forceIncrement();
+visits($post)->forceDecrement();
+```
+- This will ignore IP limitation and increment/decrement every visit.
+
+## Ignore recording extra information 
+If you want to stop recoding some of the extra information that the package collected during incrementing the counter such as country and language of visior, then just pass it to the ignore parameter
+```php
+//any of 'country', 'refer', 'periods', 'operatingSystem', 'language'
+visits('App\Post')->increment(1, false, ['country', 'language']);
+```
+or you can ignore it permanently from config/visits.php
+
+::: warning
+If you choose to ignore `periods` then you won't be able to get the count of visits during specific period of time. 
+:::

docs/6_retrieve-visits-and-stats.md

@@ -0,0 +1,52 @@
+---
+prev: 5_increments-and-decrements
+next: 7_visits-lists
+---
+
+# Retrieve visits and stats
+
+
+## An item visits
+
+#### All visits of an item
+```php
+visits($post)->count();
+```
+> **Note:** $post is a row of a model, i.e. $post = Post::find(22);
+
+#### Item's visits by a period
+```php
+visits($post)->period('day')->count();
+```
+
+## A model class visits
+
+#### All visits of a model type
+```php
+visits('App\Post')->count();
+```
+
+#### Visits of a model type in period
+```php
+visits('App\Post')->period('day')->count();
+```
+
+## Countries of visitors
+```php
+visits($post)->countries();
+```
+
+## Referers of visitors
+```php
+visits($post)->refs();
+```
+
+## Operating Systems of visitors
+```php
+visits($post)->operatingSystems();
+```
+
+## Languages of visitors
+```php
+visits($post)->languages();
+```

docs/7_visits-lists.md

@@ -0,0 +1,39 @@
+---
+prev: 6_retrieve-visits-and-stats
+next: 8_clear-and-reset-values
+---
+
+# Visits Lists
+Top or Lowest list per model type
+
+## Top/Lowest visited items per model
+```php
+visits('App\Post')->top(10);
+```
+```php
+visits('App\Post')->low(10);
+```
+
+### Filter by model attributes
+You can get only some of the top/low models by query where clause. For example if Post model has `shares` & `likes` attributes you can filter the models like this: 
+
+```php
+visits('App\Post')->top(10, [['likes', '>', 30], ['shares', '<', 20]]);
+```
+or just ...
+```php
+visits('App\Post')->top(10, ['likes' => 20]);
+```
+
+
+## Uncached list
+```php
+visits('App\Post')->fresh()->top(10);
+```
+> **Note:** you can always get uncached list by enabling `alwaysFresh` from config/visits.php file.
+
+## By a period of time
+```php
+visits('App\Post')->period('month')->top(10);
+```
+> **Note** supported periods can be found in [periods-options](8_clear-and-reset-values.html#periods-options)