PHPackages                             sierratecnologia/gamer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. sierratecnologia/gamer

ActiveLibrary[Utility & Helpers](/categories/utility)

sierratecnologia/gamer
======================

Game

0.4.4(2y ago)019MITPHPCI failing

Since Oct 6Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/SierraTecnologia/Gamer)[ Packagist](https://packagist.org/packages/sierratecnologia/gamer)[ Docs](https://sierratecnologia.com/packages/gamer/)[ Fund](https://ricasolucoes.com.br/open-source/support-us)[ GitHub Sponsors](https://github.com/ricasolucoes)[ RSS](/packages/sierratecnologia-gamer/feed)WikiDiscussions stable Synced 3w ago

READMEChangelogDependencies (19)Versions (12)Used By (0)

SierraTecnologia Gamer
======================

[](#sierratecnologia-gamer)

**SierraTecnologia Gamer** Various functionality, and basic controller included out-of-the-box.

[![Packagist](https://camo.githubusercontent.com/940b1a10353f9a89586b349eddf89ad36aba5aa5ef78f80cfb1e9efa5e99c484/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369657272617465636e6f6c6f6769612f67616d65722e7376673f6c6162656c3d5061636b6167697374267374796c653d666c61742d737175617265)](https://packagist.org/packages/sierratecnologia/gamer)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/c2b86fdb4acd0182eb7250dda4e1a39fdf6b5d337a2f5ab1c7d360efa3d574c2/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f7369657272617465636e6f6c6f6769612f67616d65722e7376673f6c6162656c3d5363727574696e697a6572267374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/sierratecnologia/gamer/)[![Travis](https://camo.githubusercontent.com/d04a380fc21efcb7886194c51a2e2a2caeda96a9a2570ee0adab73cf736ee860/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f7369657272617465636e6f6c6f6769612f67616d65722e7376673f6c6162656c3d5472617669734349267374796c653d666c61742d737175617265)](https://travis-ci.org/sierratecnologia/gamer)[![StyleCI](https://camo.githubusercontent.com/4191b35d1ee7b0da2e27c1fe2bd612ce3dfe1673a64523a762f99155892e2142/68747470733a2f2f7374796c6563692e696f2f7265706f732f36303936383838302f736869656c64)](https://styleci.io/repos/60968880)[![License](https://camo.githubusercontent.com/8b7eba25ae31c16bdf39df170450bfd4617ace755fa3e914a32e977f437a6e40/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369657272617465636e6f6c6f6769612f67616d65722e7376673f6c6162656c3d4c6963656e7365267374796c653d666c61742d737175617265)](https://github.com/sierratecnologia/gamer/blob/master/LICENSE)[![Build Status](https://github.com/sierratecnologia/gamer/workflows/CI/badge.svg)](https://github.com/sierratecnologia/gamer/actions)[![codecov](https://camo.githubusercontent.com/beeccb2d9b812c3df650a6393fdf2653b1da33081e66656615105f06ed41a324/68747470733a2f2f636f6465636f762e696f2f67682f7369657272617465636e6f6c6f6769612f67616d65722f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/sierratecnologia/gamer)

\[x\] Point Transaction system for laravel X

---

📚 Índice
--------

[](#-índice)

1. [Introdução](#-introdu%C3%A7%C3%A3o)
2. [Instalação](#-instala%C3%A7%C3%A3o)
3. [Arquitetura e Estrutura Interna](#-arquitetura-e-estrutura-interna)
4. [Principais Funcionalidades](#-principais-funcionalidades)
5. [Uso Prático](#-uso-pr%C3%A1tico)
6. [Integração com o Ecossistema SierraTecnologia](#-integra%C3%A7%C3%A3o-com-o-ecossistema-sierratecnologia)
7. [Extensão e Customização](#-extens%C3%A3o-e-customiza%C3%A7%C3%A3o)
8. [Exemplos Reais](#-exemplos-reais)
9. [Configuração de Ferramentas de Qualidade](#-configura%C3%A7%C3%A3o-de-ferramentas-de-qualidade)
10. [Guia de Contribuição](#-guia-de-contribui%C3%A7%C3%A3o)

---

🎮 Introdução
------------

[](#-introdução)

### O que é o Gamer?

[](#o-que-é-o-gamer)

**Gamer** é um módulo de gamificação completo e extensível para aplicações Laravel, desenvolvido pela **SierraTecnologia / Rica Soluções**. O pacote oferece um sistema robusto de pontuação, conquistas, competições, badges e progressão de usuários, permitindo aumentar o engajamento e a retenção de usuários em plataformas web e APIs.

### Objetivo e Motivação

[](#objetivo-e-motivação)

O projeto nasceu da necessidade de criar experiências interativas e engajadoras em plataformas corporativas, educacionais e de e-commerce. Com o **Gamer**, é possível:

- **Incentivar comportamentos desejados** através de sistemas de recompensa
- **Aumentar a retenção e engajamento** de usuários
- **Criar competições saudáveis** entre usuários ou equipes
- **Medir e rastrear progressão** através de métricas de gamificação
- **Personalizar experiências** baseadas em conquistas e níveis

### Contexto no Ecossistema SierraTecnologia

[](#contexto-no-ecossistema-sierratecnologia)

O **Gamer** faz parte do ecossistema modular da **SierraTecnologia / Rica Soluções**, integrando-se nativamente com outros módulos como:

- **Informate** - Sistema de notificações e comunicação
- **Market** - Plataforma de e-commerce
- **CMS** - Sistema de gerenciamento de conteúdo
- **Tracking** - Rastreamento e analytics
- **Finder** - Sistema de busca e descoberta

### Benefícios para Plataformas de Engajamento

[](#benefícios-para-plataformas-de-engajamento)

- ✅ **Sistema de pontuação flexível** com suporte a múltiplos tipos de pontos
- ✅ **Histórico completo de transações** com rastreabilidade total
- ✅ **Event-driven architecture** utilizando Spatie Event Sourcing
- ✅ **Observers automáticos** para eventos de Eloquent e autenticação
- ✅ **Dashboard administrativo** completo com interface AdminLTE
- ✅ **APIs RESTful** para integração com aplicações frontend
- ✅ **Sistema de competições** com times e jogadores
- ✅ **Extensível e customizável** através de traits, contratos e eventos

---

📦 Instalação
------------

[](#-instalação)

### Requisitos Mínimos

[](#requisitos-mínimos)

- **PHP**: `>= 7.4` (recomendado `>= 8.2`)
- **Laravel**: `^6.0 | ^7.0 | ^8.0 | ^9.0 | ^10.0 | ^11.0`
- **Composer**: `^2.0`
- **Banco de Dados**: MySQL `>= 5.7`, PostgreSQL `>= 9.6` ou SQLite `>= 3.8`

### Dependências Principais

[](#dependências-principais)

- `sierratecnologia/audit` - Sistema de auditoria
- `sierratecnologia/pedreiro` - Componentes base
- `sierratecnologia/muleta` - Utilitários e helpers
- `spatie/laravel-event-sourcing` - Event Sourcing
- `lorisleiva/laravel-actions` - Actions pattern

### Instalação via Composer

[](#instalação-via-composer)

```
composer require sierratecnologia/gamer
```

### Publicação de Configurações e Migrations

[](#publicação-de-configurações-e-migrations)

Após a instalação, publique os arquivos de configuração e execute as migrations:

```
# Publicar configurações
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=config

# Publicar migrations
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=migrations

# Executar migrations
php artisan migrate
```

### Publicação de Assets e Views (Opcional)

[](#publicação-de-assets-e-views-opcional)

```
# Publicar views
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=views

# Publicar traduções
php artisan vendor:publish --provider="Gamer\GamerProvider" --tag=lang
```

### Registro de Service Provider

[](#registro-de-service-provider)

O **Service Provider** é registrado automaticamente através do Laravel Auto-Discovery. Caso necessário, adicione manualmente em `config/app.php`:

```
'providers' => [
    // ...
    Gamer\GamerProvider::class,
];
```

### Configuração do Arquivo `.env`

[](#configuração-do-arquivo-env)

Para integração com serviços externos, adicione ao `.env`:

```
# Integração com Pointagram (opcional)
SERVICES_POINTAGRAM_KEY=seu_token_aqui
```

---

🏗️ Arquitetura e Estrutura Interna
----------------------------------

[](#️-arquitetura-e-estrutura-interna)

### Estrutura de Diretórios

[](#estrutura-de-diretórios)

```
src/
├── Aggregates/          # Event Sourcing Aggregates
├── Builders/            # Query Builders customizados
├── Console/             # Comandos Artisan
│   └── Commands/
├── Connectors/          # Conectores com serviços externos
├── Contracts/           # Interfaces e Contratos
│   └── Pointable.php    # Contrato para entidades pontuáveis
├── Entities/            # Value Objects e Entidades de Domínio
│   └── Points/
├── Events/              # Eventos de Domínio
├── Facades/             # Facades do Laravel
├── Http/                # Camada HTTP
│   ├── Controllers/     # Controllers (User, Painel, RiCa)
│   ├── Middleware/      # Middlewares
│   └── Requests/        # Form Requests
├── Models/              # Eloquent Models
├── Notifications/       # Notificações
├── Observers/           # Eloquent Observers
├── Policies/            # Authorization Policies
├── Pointable/           # Sistema de pontuação
│   └── Mapeamento/
├── Processing/          # Processadores de lógica de negócio
├── Reactors/            # Event Sourcing Reactors
├── Repositories/        # Repositories Pattern
├── Services/            # Camada de Serviços
├── Traits/              # Traits reutilizáveis
│   ├── Pointable.php    # Trait principal de gamificação
│   └── AsPointable.php  # Trait auxiliar
├── Gamer.php            # Classe principal
└── GamerProvider.php    # Service Provider

```

### Componentes Centrais

[](#componentes-centrais)

#### 1. **Sistema de Pontos e Transações**

[](#1-sistema-de-pontos-e-transações)

- **`Transaction`** (Model): Representa uma transação de pontos, armazenando quantidade, mensagem, saldo atual e relacionamento polimórfico com a entidade pontuável.
- **`Point`** (Model): Representa tipos de pontos (ex: XP, moedas, estrelas).
- **`PointType`** (Model): Define categorias de pontos com regras específicas.

#### 2. **Trait Pointable**

[](#2-trait-pointable)

```
// src/Traits/Pointable.php
trait Pointable
{
    public function transactions($amount = null);      // Relacionamento com transações
    public function points();                           // Relacionamento com tipos de pontos
    public function countTransactions();                // Contagem de transações
    public function currentPoints();                    // Saldo atual de pontos
    public function addPoints($amount, $message, $data = null); // Adicionar pontos
}
```

**Funcionalidades:**

- Relacionamento polimórfico com `Transaction` e `Point`
- Cálculo automático de saldo atual
- Histórico completo de transações
- Suporte a metadados customizados

#### 3. **Sistema de Competições**

[](#3-sistema-de-competições)

- **`Competition`** (Model): Gerencia competições/desafios
- **`Team`** (Model): Gerencia equipes
- **`Player`** (Model): Gerencia jogadores
- **`CompetitionPlayer`** (Model): Relacionamento entre competições e jogadores

#### 4. **Sistema de Scores e Séries**

[](#4-sistema-de-scores-e-séries)

- **`ScoreSerie`** (Model): Gerencia séries de pontuação
- **`ScoreSeriePointType`** (Model): Relacionamento entre séries e tipos de pontos

#### 5. **Sistema de Eventos**

[](#5-sistema-de-eventos)

- **`GamerEvent`** (Model): Gerencia eventos de gamificação
- **`EventPointable`** (Processing): Processa eventos e atribui pontos

#### 6. **Observers**

[](#6-observers)

- **`ModelCallbacks`**: Observa todos os eventos Eloquent (`created`, `updated`, `deleted`)
- **`LoginObserver`**: Observa eventos de login para atribuir pontos automaticamente

### Padrões Arquiteturais

[](#padrões-arquiteturais)

#### Event-Driven Architecture

[](#event-driven-architecture)

O **Gamer** utiliza **Spatie Event Sourcing** para rastreamento completo de eventos:

```
// Eventos registrados no GamerProvider
$this->app['events']->listen(
    'eloquent.*',
    'Gamer\Observers\ModelCallbacks'
);

$this->app['events']->listen(
    'Illuminate\Auth\Events\Login',
    'Gamer\Observers\LoginObserver'
);
```

#### Repository Pattern

[](#repository-pattern)

Exemplo de Repository:

```
// src/Repositories/PromotionRepository.php
class PromotionRepository
{
    // Lógica de acesso a dados isolada
}
```

#### Service Layer

[](#service-layer)

```
// src/Services/GamerService.php
class GamerService
{
    // Lógica de negócio centralizada
}
```

### Comunicação entre Camadas

[](#comunicação-entre-camadas)

```
┌─────────────┐
│  Controller │ → HTTP Request
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Service   │ → Lógica de Negócio
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Repository  │ → Acesso a Dados
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    Model    │ → Eloquent ORM
└─────────────┘

```

### Integração com Eloquent

[](#integração-com-eloquent)

O sistema utiliza **relacionamentos polimórficos** para máxima flexibilidade:

```
// Qualquer modelo pode ser "Pointable"
class User extends Model implements Pointable
{
    use PointableTrait;
}

// Relacionamento polimórfico
$user->transactions()->save($transaction);
```

---

🚀 Principais Funcionalidades
----------------------------

[](#-principais-funcionalidades)

### 1. Sistema de Pontuação e Níveis

[](#1-sistema-de-pontuação-e-níveis)

#### Adicionar Pontos

[](#adicionar-pontos)

```
$user = User::first();
$user->addPoints(100, 'Completou tutorial');

// Com metadados personalizados
$user->addPoints(50, 'Primeira compra', [
    'ref_id' => 'ORDER-123',
    'category' => 'sales'
]);
```

#### Consultar Saldo Atual

[](#consultar-saldo-atual)

```
$currentPoints = $user->currentPoints(); // 150.0
```

#### Histórico de Transações

[](#histórico-de-transações)

```
// Todas as transações
$transactions = $user->transactions;

// Últimas 5 transações
$lastTransactions = $user->transactions(5)->get();

// Contagem total
$total = $user->countTransactions();
```

### 2. Sistema de Conquistas e Badges

[](#2-sistema-de-conquistas-e-badges)

*(Em desenvolvimento - estrutura preparada em migrations)*

```
// Estrutura planejada
$user->badges()->attach($badgeId);
$user->achievements()->where('unlocked', true)->get();
```

### 3. Eventos Automáticos de Gamificação

[](#3-eventos-automáticos-de-gamificação)

O sistema observa automaticamente eventos do Laravel:

#### Eventos de Autenticação

[](#eventos-de-autenticação)

```
// LoginObserver.php - Pontos automáticos ao fazer login
Event::listen('Illuminate\Auth\Events\Login', function($event) {
    $event->user->addPoints(10, 'Login diário');
});
```

#### Eventos de Eloquent

[](#eventos-de-eloquent)

```
// ModelCallbacks.php - Pontos por ações em modelos
Event::listen('eloquent.created', function($model) {
    if ($model instanceof Post) {
        $model->user->addPoints(50, 'Criou um novo post');
    }
});
```

### 4. Sistema de Competições

[](#4-sistema-de-competições)

```
// Criar competição
$competition = Competition::create([
    'name' => 'Desafio de Vendas Q1',
    'start_date' => now(),
    'end_date' => now()->addMonths(3),
]);

// Adicionar jogadores
$competition->players()->attach($userId);

// Criar time
$team = Team::create(['name' => 'Time Alpha']);
$team->players()->attach($playerIds);
```

### 5. Dashboard e APIs de Ranking

[](#5-dashboard-e-apis-de-ranking)

#### Controllers Disponíveis

[](#controllers-disponíveis)

- **User Controllers** (`src/Http/Controllers/User/`):

    - `HomeController` - Dashboard do usuário
- **Painel Controllers** (`src/Http/Controllers/Painel/`):

    - `ObjectiveController` - Gerenciar objetivos
    - `MetaController` - Gerenciar metas
- **RiCa Controllers** (`src/Http/Controllers/RiCa/`):

    - `PointController` - CRUD de pontos
    - `PointTypeController` - CRUD de tipos de pontos
    - `TransactionController` - Histórico de transações
    - `CompetitionController` - Gerenciar competições
    - `PlayerController` - Gerenciar jogadores
    - `TeamController` - Gerenciar times
    - `ScoreSerieController` - Gerenciar séries de score
    - `GamerEventController` - Gerenciar eventos

#### Rotas Disponíveis

[](#rotas-disponíveis)

```
// Rotas de usuário
Route::get('profile/gamer/home', 'User\HomeController@index')
    ->name('profile.gamer.home');

// Rotas administrativas (RiCa)
Route::resource('rica/gamer/points', 'RiCa\PointController');
Route::resource('rica/gamer/transactions', 'RiCa\TransactionController');
Route::resource('rica/gamer/competitions', 'RiCa\CompetitionController');
```

### 6. Exemplo Prático de Fluxo Completo

[](#6-exemplo-prático-de-fluxo-completo)

```
// 1. Usuário realiza uma ação (ex: compra um produto)
$order = Order::create([...]);

// 2. Evento é disparado
event(new OrderCreated($order));

// 3. Observer captura e atribui pontos
// EventPointable.php ou Listener customizado
$order->user->addPoints(
    $order->total * 0.1, // 10% do valor em pontos
    'Compra no valor de R$ ' . $order->total,
    ['order_id' => $order->id]
);

// 4. Sistema verifica conquistas
if ($order->user->countTransactions() >= 10) {
    $order->user->badges()->attach($badge10Compras);
    // 5. Notificação é enviada
    $order->user->notify(new BadgeUnlocked($badge10Compras));
}

// 6. Pontos são exibidos no dashboard
return view('gamer::profile.home', [
    'currentPoints' => $order->user->currentPoints(),
    'recentTransactions' => $order->user->transactions(5)->get(),
]);
```

---

💻 Uso Prático
-------------

[](#-uso-prático)

### Como Implementar o Sistema de Pontos em um Projeto Laravel

[](#como-implementar-o-sistema-de-pontos-em-um-projeto-laravel)

#### Passo 1: Implementar o Contrato e Trait

[](#passo-1-implementar-o-contrato-e-trait)

```