Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add docs #66

Merged
merged 2 commits into from
Feb 3, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/1_introduction.md
Original file line number Diff line number Diff line change
@@ -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).
17 changes: 17 additions & 0 deletions docs/2_requirements.md
Original file line number Diff line number Diff line change
@@ -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.

118 changes: 118 additions & 0 deletions docs/3_installation.md
Original file line number Diff line number Diff line change
@@ -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.
72 changes: 72 additions & 0 deletions docs/4_quick-start.md
Original file line number Diff line number Diff line change
@@ -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();
```
61 changes: 61 additions & 0 deletions docs/5_increments-and-decrements.md
Original file line number Diff line number Diff line change
@@ -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.
:::
52 changes: 52 additions & 0 deletions docs/6_retrieve-visits-and-stats.md
Original file line number Diff line number Diff line change
@@ -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();
```
39 changes: 39 additions & 0 deletions docs/7_visits-lists.md
Original file line number Diff line number Diff line change
@@ -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)
Loading