PHPackages                             sierratecnologia/market - 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. sierratecnologia/market

ActiveLibrary

sierratecnologia/market
=======================

market

0.4.4(2y ago)05MITPHPPHP ^7.2|^8.0

Since Aug 17Pushed 6mo ago1 watchersCompare

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

READMEChangelogDependencies (7)Versions (25)Used By (0)

SierraTecnologia Market
=======================

[](#sierratecnologia-market)

**SierraTecnologia Market** integration services market and providers for users required by various SierraTecnologia packages. Validator functionality, and basic controller included out-of-the-box.

[![Packagist](https://camo.githubusercontent.com/b70d64a6983ad12adc81d5e9829ee781d4937df70ed0d44c6f96176f76aa4e8b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369657272617465636e6f6c6f6769612f6d61726b65742e7376673f6c6162656c3d5061636b6167697374267374796c653d666c61742d737175617265)](https://packagist.org/packages/sierratecnologia/market)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/351609a853c445062c05fbe014f84cca9edc011bbbc81b9a84c9767f291d4775/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f7369657272617465636e6f6c6f6769612f6d61726b65742e7376673f6c6162656c3d5363727574696e697a6572267374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/sierratecnologia/market/)[![Travis](https://camo.githubusercontent.com/6a01e3811535614512def4860e9db532b20b8345702b00300fe4719b4c192746/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f7369657272617465636e6f6c6f6769612f6d61726b65742e7376673f6c6162656c3d5472617669734349267374796c653d666c61742d737175617265)](https://travis-ci.org/sierratecnologia/market)[![StyleCI](https://camo.githubusercontent.com/4191b35d1ee7b0da2e27c1fe2bd612ce3dfe1673a64523a762f99155892e2142/68747470733a2f2f7374796c6563692e696f2f7265706f732f36303936383838302f736869656c64)](https://styleci.io/repos/60968880)[![License](https://camo.githubusercontent.com/1078573da7c0891e40fa40c5a9cc07a47679df8dd9f8e7e301e6039712f5618c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369657272617465636e6f6c6f6769612f6d61726b65742e7376673f6c6162656c3d4c6963656e7365267374796c653d666c61742d737175617265)](https://github.com/sierratecnologia/market/blob/master/LICENSE)

---

📚 Índice
--------

[](#-índice)

- [Introdução](#-introdu%C3%A7%C3%A3o)
- [Instalação](#-instala%C3%A7%C3%A3o)
- [Arquitetura e Estrutura Interna](#-arquitetura-e-estrutura-interna)
- [Principais Funcionalidades](#-principais-funcionalidades)
- [Uso Prático](#-uso-pr%C3%A1tico)
- [Integração com o Ecossistema SierraTecnologia](#-integra%C3%A7%C3%A3o-com-o-ecossistema-sierratecnologia)
- [Extensão e Customização](#-extens%C3%A3o-e-customiza%C3%A7%C3%A3o)
- [Exemplos Reais](#-exemplos-reais)
- [Guia de Contribuição](#-guia-de-contribui%C3%A7%C3%A3o)
- [Testes e Qualidade](#-testes-e-qualidade)
- [Changelog](#changelog)
- [Suporte](#suporte)

---

🚀 Introdução
------------

[](#-introdução)

### O que é o Market?

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

**Market** é uma solução modular completa de **e-commerce e marketplace** desenvolvida pela **SierraTecnologia / Rica Soluções**, projetada para integração nativa com aplicações Laravel. O pacote oferece uma camada robusta e escalável para gerenciamento de produtos, carrinho de compras, processamento de pagamentos, gestão de pedidos e assinaturas recorrentes.

### Objetivo e Contexto de Uso

[](#objetivo-e-contexto-de-uso)

O Market integra o ecossistema **SierraTecnologia**, servindo como módulo central para operações comerciais em aplicações corporativas e startups que necessitam de:

- **Catálogo de produtos** com variantes e gestão de estoque
- **Carrinho de compras** persistente e seguro
- **Checkout completo** com múltiplos métodos de pagamento
- **Gestão de pedidos** e transações financeiras
- **Assinaturas e planos recorrentes**
- **Sistema de cupons e descontos**
- **Analytics e relatórios comerciais**

### Principais Benefícios e Diferenciais

[](#principais-benefícios-e-diferenciais)

✅ **Modularidade**: Arquitetura desacoplada seguindo princípios SOLID ✅ **Escalabilidade**: Suporte a múltiplos marketplaces e multi-tenancy ✅ **Integração Nativa**: Comunicação fluida com Payment-Laravel, Pedreiro, Media-Manager ✅ **Flexibilidade**: Sistema de variantes dinâmicas com modificadores de preço/peso ✅ **Segurança**: Criptografia de IDs sensíveis, validação robusta, proteção CSRF ✅ **Analytics Avançado**: Dashboard com métricas de vendas, refundos e assinaturas ✅ **Multi-canal**: APIs REST para integração com mobile e SPAs

### Relação com o Ecossistema Rica Soluções

[](#relação-com-o-ecossistema-rica-soluções)

O Market se comunica com outros pacotes da SierraTecnologia através de contratos e interfaces bem definidas:

```
Market (Commerce Core)
    ├── Payment-Laravel (Gateway de Pagamento)
    ├── Pedreiro (Admin Scaffolding)
    ├── Media-Manager (Gestão de Imagens/Arquivos)
    ├── Crypto (Criptografia e UUID)
    ├── Bancario (Integrações Bancárias)
    ├── Muleta (Utilitários Base)
    └── Locaravel (Localização e URLs)

```

---

💿 Instalação
------------

[](#-instalação)

### Requisitos Mínimos

[](#requisitos-mínimos)

- **PHP**: ^7.2 | ^8.0 | ^8.1 | ^8.2
- **Laravel**: ^7.0 | ^8.0 | ^9.0 | ^10.0
- **Extensões PHP**: `mbstring`, `openssl`, `pdo`, `tokenizer`, `json`, `curl`
- **Banco de Dados**: MySQL 5.7+ / PostgreSQL 9.6+ / MariaDB 10.2+

### Instalação via Composer

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

```
composer require sierratecnologia/market
```

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

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

```
# Publicar arquivo de configuração
php artisan vendor:publish --tag=sitec-config

# Publicar views (opcional, para customização)
php artisan vendor:publish --tag=sitec-views

# Publicar traduções
php artisan vendor:publish --tag=sitec-lang

# Publicar assets públicos (CSS/JS)
php artisan vendor:publish --tag=sitec-public
```

### Executar Migrações

[](#executar-migrações)

```
php artisan migrate
```

Isso criará as tabelas:

- `products` - Catálogo de produtos
- `product_variants` - Variantes (tamanho, cor, etc.)
- `cart` - Carrinho de compras
- `orders` - Pedidos
- `order_items` - Itens dos pedidos
- `transactions` - Transações financeiras
- `refunds` - Reembolsos
- `plans` - Planos de assinatura
- `coupons` - Cupons de desconto
- `favorites` - Lista de desejos

### Registro de Service Providers e Aliases

[](#registro-de-service-providers-e-aliases)

**Registro Automático (Laravel 5.5+)**

O `MarketProvider` é registrado automaticamente via Package Discovery.

**Registro Manual (Laravel 5.4 ou inferior)**

Adicione ao `config/app.php`:

```
'providers' => [
    // ...
    Market\MarketProvider::class,
],

'aliases' => [
    // ...
    'Market' => Market\Facades\Market::class,
    'StoreHelper' => Market\Facades\StoreHelper::class,
],
```

### Configuração Inicial

[](#configuração-inicial)

Edite `config/sitec/market.php`:

```
return [
    // Habilitar suporte a múltiplos marketplaces
    'multi-markets' => true,

    // Habilitar sistema de planos/assinaturas
    'have-plans' => true,

    // Habilitar sistema de cupons
    'have-coupons' => true,

    // Prefixo de URL da loja
    'store_url_prefix' => 'commerce',

    // Moeda padrão (ISO 4217)
    'currency' => 'BRL',

    // Incluir frete no cálculo de impostos
    'taxes_include_shipping' => true,
];
```

Configure suas credenciais de pagamento no `.env`:

```
SITECPAYMENT_SECRET=sk_test_xxxxxxxxxxxxx
SITECPAYMENT_PUBLIC=pk_test_xxxxxxxxxxxxx
```

---

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

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

### Organização dos Diretórios e Namespaces

[](#organização-dos-diretórios-e-namespaces)

```
src/
├── Cacheable/              # Utilitários de cache para queries Eloquent
├── Console/                # Comandos Artisan e Kernel customizado
├── Contracts/              # Contratos abstratos e interfaces
├── Exceptions/             # Exceções customizadas do domínio
├── Facades/                # Facades (Market, StoreHelper)
├── Http/
│   ├── Controllers/        # Controladores MVC
│   │   ├── Admin/         # Painel administrativo (CRUD)
│   │   ├── Api/           # Endpoints REST (cart, favorites)
│   │   └── Master/        # Dashboard de analytics
│   ├── Policies/          # Políticas de autorização
│   └── Requests/          # Form Requests (validação)
├── Interfaces/            # Contratos de serviços e repositórios
├── Models/                # Modelos Eloquent (14 models)
├── Observers/             # Observadores de eventos de modelo
├── Repositories/          # Camada de acesso a dados (10 repos)
├── Resources/             # API Resources (serialização JSON)
├── Scopes/                # Query Scopes globais/locais
├── Services/              # Lógica de negócio (19 services)
├── Traits/                # Funcionalidades reutilizáveis
├── Market.php             # Classe principal do pacote
└── MarketProvider.php     # Service Provider Laravel

```

### Padrões Arquiteturais

[](#padrões-arquiteturais)

O Market implementa uma arquitetura em camadas inspirada em **Domain-Driven Design (DDD)** e **Clean Architecture**:

#### 1. **Camada de Domínio (Domain Layer)**

[](#1-camada-de-domínio-domain-layer)

Contém as regras de negócio puras e entidades do domínio:

```
// Models (Entidades)
Market\Models\Product        # Produtos do catálogo
Market\Models\Order          # Pedidos (Aggregate Root)
Market\Models\OrderItem      # Itens do pedido
Market\Models\Transaction    # Transações financeiras
Market\Models\Cart           # Carrinho de compras
Market\Models\Variant        # Variantes de produtos

// Value Objects
Market\Models\Currency       # Objeto de valor monetário
```

**Exemplo de Aggregate Root (Order)**:

```
namespace Market\Models;

class Order extends MarketModel
{
    // Aggregate que coordena OrderItems e Transaction
    public function items()
    {
        return $this->hasMany(OrderItem::class);
    }

    public function transaction()
    {
        return $this->belongsTo(Transaction::class);
    }

    // Regra de negócio: cancelamento cascata
    public function cancel()
    {
        foreach ($this->items as $item) {
            $item->refund();
        }
        $this->transaction->refund();
        $this->update(['status' => 'cancelled']);
    }
}
```

#### 2. **Camada de Aplicação (Application Layer)**

[](#2-camada-de-aplicação-application-layer)

Orquestra casos de uso através de **Services**:

```
// Serviços (Casos de Uso)
Market\Services\CartService           # Gerenciamento do carrinho
Market\Services\PaymentService        # Processamento de pagamentos
Market\Services\OrderService          # Gestão de pedidos
Market\Services\ProductService        # CRUD de produtos
Market\Services\LogisticService       # Cálculo de frete e impostos
Market\Services\AnalyticsService      # Métricas e relatórios
```

**Exemplo de Service (PaymentService)**:

```
namespace Market\Services;

class PaymentService
{
    protected $transactionService;
    protected $orderService;
    protected $logisticService;

    public function __construct(
        TransactionService $transactionService,
        OrderService $orderService,
        LogisticService $logisticService
    ) {
        $this->transactionService = $transactionService;
        $this->orderService = $orderService;
        $this->logisticService = $logisticService;
    }

    public function purchase($user, $cardToken, $cart)
    {
        DB::beginTransaction();

        try {
            // 1. Processar pagamento via gateway
            $charge = $user->meta->charge(
                $cart->total(),
                $cardToken
            );

            // 2. Registrar transação
            $transaction = $this->transactionService->create([
                'user_id' => $user->id,
                'provider' => 'sitecpayment',
                'provider_id' => $charge->id,
                'amount' => $cart->total(),
            ]);

            // 3. Criar pedido
            $order = $this->createOrder($user, $transaction, $cart);

            // 4. Processar logística
            $this->logisticService->afterPurchase($order);

            // 5. Limpar carrinho
            $cart->empty();

            DB::commit();
            return $order;

        } catch (\Exception $e) {
            DB::rollBack();
            throw new PaymentException($e->getMessage());
        }
    }
}
```

#### 3. **Camada de Infraestrutura (Infrastructure Layer)**

[](#3-camada-de-infraestrutura-infrastructure-layer)

Implementa persistência e integrações externas:

```
// Repositórios (Data Access)
Market\Repositories\ProductRepository
Market\Repositories\OrderRepository
Market\Repositories\CartRepository
Market\Repositories\TransactionRepository

// Service Provider (Dependency Injection)
Market\MarketProvider

// Migrations (Schema Management)
database/migrations/
```

**Exemplo de Repository Pattern**:

```
namespace Market\Repositories;

class ProductRepository
{
    protected $model;

    public function __construct(Product $model)
    {
        $this->model = $model;
    }

    public function paginated($perPage = 25)
    {
        return $this->model
            ->where('is_published', true)
            ->where('is_available', true)
            ->orderBy('created_at', 'desc')
            ->paginate($perPage);
    }

    public function findByURL($url)
    {
        return $this->model
            ->where('url', $url)
            ->firstOrFail();
    }
}
```

### Convenções da SierraTecnologia para Modularidade e Escalabilidade

[](#convenções-da-sierratecnologia-para-modularidade-e-escalabilidade)

1. **Injeção de Dependência**: Todos os services usam constructor injection
2. **Interface Segregation**: Contratos específicos em `Interfaces/`
3. **Single Responsibility**: Cada service tem uma responsabilidade única
4. **Repository Pattern**: Abstração de acesso a dados
5. **Facades Opcionais**: Acesso via DI ou Facades conforme preferência
6. **Event Observers**: Callbacks de modelo centralizados
7. **Configuração Centralizada**: `config/sitec/market.php`
8. **Logging Dedicado**: Canal `sitec-market` separado

---

🎯 Principais Funcionalidades
----------------------------

[](#-principais-funcionalidades)

### 1. Gestão de Produtos

[](#1-gestão-de-produtos)

#### Estrutura do Modelo Product

[](#estrutura-do-modelo-product)

```
namespace Market\Models;

class Product extends MarketModel
{
    protected $fillable = [
        'name',              // Nome do produto
        'url',               // Slug URL-friendly
        'code',              // SKU/Código interno
        'price',             // Preço em centavos (int)
        'weight',            // Peso em gramas (int)
        'width',             // Largura em cm
        'height',            // Altura em cm
        'depth',             // Profundidade em cm
        'discount',          // Desconto em centavos
        'stock',             // Quantidade em estoque
        'is_published',      // Publicado?
        'is_available',      // Disponível?
        'is_featured',       // Produto destaque?
        'hero_image',        // Imagem principal (path)
        'file',              // Arquivo digital (downloads)
        'details',           // JSON: descrição, SEO, etc.
    ];

    // Accessors para conversão automática
    public function getPriceAttribute($value)
    {
        return $value / 100; // centavos → reais
    }

    public function setPriceAttribute($value)
    {
        $this->attributes['price'] = $value * 100; // reais → centavos
    }

    // Relacionamentos
    public function variants()
    {
        return $this->hasMany(Variant::class);
    }

    public function images()
    {
        return $this->hasMany(Image::class, 'entity_id')
                    ->where('entity_type', self::class);
    }
}
```

#### Criando Produtos via Service

[](#criando-produtos-via-service)

```
use Market\Services\ProductService;

$productService = app(ProductService::class);

$product = $productService->create([
    'name' => 'Notebook Dell XPS 15',
    'url' => 'notebook-dell-xps-15',
    'code' => 'DELL-XPS15-2024',
    'price' => 8999.90,  // Será armazenado como 899990 centavos
    'weight' => 1800,    // 1.8kg em gramas
    'stock' => 50,
    'is_published' => true,
    'is_available' => true,
    'details' => [
        'description' => 'Notebook de alta performance...',
        'specs' => [
            'processor' => 'Intel Core i7',
            'ram' => '16GB DDR4',
            'storage' => 'SSD 512GB NVMe'
        ],
        'seo' => [
            'meta_description' => 'Compre o melhor notebook...',
            'keywords' => 'notebook, dell, xps'
        ]
    ]
]);
```

### 2. Sistema de Variantes Avançado

[](#2-sistema-de-variantes-avançado)

O Market suporta variantes com **modificadores de preço e peso**:

```
// Criando variantes
$variant1 = $product->variants()->create([
    'key' => 'cor',
    'value' => 'Prata(+$0)[+0g]'  // Sem modificadores
]);

$variant2 = $product->variants()->create([
    'key' => 'cor',
    'value' => 'Dourado(+$299.90)[+50g]'  // +R$299,90 e +50g
]);

$variant3 = $product->variants()->create([
    'key' => 'memoria',
    'value' => '32GB(+$899.00)[+0g]'  // Upgrade de RAM
]);
```

**Sintaxe de Modificadores**:

- `(+$valor)` ou `(-$valor)`: Ajuste de preço
- `[+peso]` ou `[-peso]`: Ajuste de peso em gramas
- Múltiplas variantes: `"Cor|Tamanho|Material"`

**Cálculo Automático no Carrinho**:

```
// Adicionar ao carrinho com variantes
$cart->add([
    'product_id' => $product->id,
    'quantity' => 1,
    'variants' => 'Dourado|32GB',  // +R$1.198,90
]);

// Preço calculado:
// Base: R$8.999,90
// + Cor Dourado: R$299,90
// + 32GB RAM: R$899,00
// = R$10.198,80
```

### 3. Carrinho de Compras

[](#3-carrinho-de-compras)

#### Dual Storage: Sessão (Guest) + Database (User)

[](#dual-storage-sessão-guest--database-user)

```
use Market\Services\CartService;

$cartService = app(CartService::class);

// Adicionar item ao carrinho
$cartService->addToCart([
    'product_id' => 1,
    'quantity' => 2,
    'variants' => 'Vermelho|Grande',
]);

// Obter conteúdo do carrinho
$items = $cartService->contents();

// Totais
$subtotal = $cartService->getCartSubTotal();  // Soma dos produtos
$tax = $cartService->getCartTax();            // Impostos
$shipping = $cartService->getCartShipping();  // Frete
$total = $cartService->getCartTotal();        // Total final

// Aplicar cupom
$cartService->addCoupon('DESCONTO10');

// Remover item
$cartService->removeFromCart($itemId);

// Esvaziar carrinho
$cartService->emptyCart();
```

#### Sincronização Automática (Guest → User)

[](#sincronização-automática-guest--user)

Quando um usuário não autenticado faz login, o carrinho da sessão é automaticamente mesclado com o carrinho do banco de dados:

```
// Em CartRepository@syncronize()
public function syncronize($userId)
{
    $sessionCart = session()->get('cart', []);

    foreach ($sessionCart as $item) {
        $this->model->create([
            'user_id' => $userId,
            'product_id' => $item['product_id'],
            'quantity' => $item['quantity'],
            'variants' => $item['variants'],
        ]);
    }

    session()->forget('cart');
}
```

### 4. Checkout e Processamento de Pagamentos

[](#4-checkout-e-processamento-de-pagamentos)

#### Fluxo Completo de Checkout

[](#fluxo-completo-de-checkout)

```
// 1. Página de Confirmação (/checkout)
// Usuário revisa itens, endereço, frete

// 2. Página de Pagamento (/payment)
// Usuário insere dados do cartão

// 3. Processar Pagamento (POST /process)
use Market\Services\PaymentService;

$paymentService = app(PaymentService::class);

$order = $paymentService->purchase(
    auth()->user(),
    $request->input('card_token'),  // Token do gateway
    $cartService->getCart()
);

// 4. Página de Sucesso (/complete)
// Exibir número do pedido e detalhes
```

#### Integração com Payment-Laravel (SierraTecnologia Gateway)

[](#integração-com-payment-laravel-sierratecnologia-gateway)

```
// O usuário precisa ter um customer_id no gateway
if (!auth()->user()->meta->hasCustomer()) {
    auth()->user()->meta->createAsSierraTecnologiaCustomer(
        $request->input('card_token')
    );
}

// Cobrar do cartão
$charge = auth()->user()->meta->charge(
    $cart->total(),
    $request->input('card_token')
);

// Cobrar do último cartão salvo
$charge = auth()->user()->meta->chargeWithLastCard($amount);
```

### 5. Gestão de Pedidos e Transações

[](#5-gestão-de-pedidos-e-transações)

#### Estrutura de Pedido (Order)

[](#estrutura-de-pedido-order)

```
namespace Market\Models;

class Order extends MarketModel
{
    protected $fillable = [
        'uuid',                  // UUID único do pedido
        'user_id',              // Cliente
        'transaction_id',       // Transação associada
        'shipping_address',     // JSON: endereço de entrega
        'billing_address',      // JSON: endereço de cobrança
        'is_shipped',           // Enviado?
        'tracking_number',      // Código de rastreio
        'status',               // pending|complete|cancelled
        'notes',                // Observações
        'details',              // JSON: metadados adicionais
    ];

    protected $casts = [
        'shipping_address' => 'array',
        'billing_address' => 'array',
        'details' => 'array',
    ];
}
```

#### Criando e Gerenciando Pedidos

[](#criando-e-gerenciando-pedidos)

```
use Market\Services\OrderService;

$orderService = app(OrderService::class);

// Criar pedido
$order = $orderService->create([
    'user_id' => $user->id,
    'transaction_id' => $transaction->id,
    'shipping_address' => [
        'street' => 'Rua das Flores, 123',
        'city' => 'Rio de Janeiro',
        'state' => 'RJ',
        'zipcode' => '20000-000',
    ],
    'items' => [
        ['product_id' => 1, 'quantity' => 2, 'variants' => 'Azul|M'],
        ['product_id' => 5, 'quantity' => 1, 'variants' => null],
    ],
]);

// Buscar pedidos do cliente
$orders = $orderService->getByCustomer($user->id);

// Cancelar pedido (refund automático)
$orderService->cancel($order->id);

// Atualizar status de envio
$orderService->update($order->id, [
    'is_shipped' => true,
    'tracking_number' => 'BR123456789XY',
]);
```

### 6. Sistema de Assinaturas (Plans)

[](#6-sistema-de-assinaturas-plans)

#### Criando Planos

[](#criando-planos)

```
use Market\Services\PlanService;

$planService = app(PlanService::class);

$plan = $planService->create([
    'name' => 'Premium Mensal',
    'amount' => 49.90,           // R$49,90/mês
    'interval' => 'month',       // week|month|year
    'currency' => 'BRL',
    'trial_days' => 7,           // 7 dias grátis
    'is_featured' => true,
    'enabled' => true,
    'descriptors' => [
        'features' => [
            'Acesso ilimitado',
            'Suporte prioritário',
            'Downloads sem limite'
        ]
    ]
]);
```

#### Assinando um Plano

[](#assinando-um-plano)

```
use Market\Services\SubscriptionService;

$subscriptionService = app(SubscriptionService::class);

// Criar assinatura
$subscription = auth()->user()->meta->newSubscription(
    'Premium Mensal',
    $plan->sitecpayment_id
)->create($cardToken);

// Cancelar assinatura
auth()->user()->meta->subscription('Premium Mensal')->cancel();

// Verificar se está assinado
if (auth()->user()->meta->subscribed('Premium Mensal')) {
    // Usuário tem acesso premium
}
```

### 7. Cupons e Descontos

[](#7-cupons-e-descontos)

```
use Market\Services\CouponService;

$couponService = app(CouponService::class);

// Criar cupom de 10% de desconto
$coupon = $couponService->create([
    'code' => 'DESCONTO10',
    'discount_type' => 'percentage',  // ou 'dollar'
    'amount' => 10,                   // 10%
    'limit' => 100,                   // Máximo 100 usos
    'start_date' => now(),
    'end_date' => now()->addDays(30),
    'for_subscriptions' => false,
]);

// Criar cupom de R$50 off
$coupon = $couponService->create([
    'code' => '50REAIS',
    'discount_type' => 'dollar',
    'amount' => 50.00,
    'limit' => 50,
]);

// Aplicar cupom no checkout
$cartService->addCoupon('DESCONTO10');
```

### 8. Analytics e Relatórios

[](#8-analytics-e-relatórios)

```
use Market\Services\AnalyticsService;

$analyticsService = app(AnalyticsService::class);

// Obter transações dos últimos 30 dias
$transactions = $analyticsService->getTransactionsByDays(30);

// Calcular balanço (receita - reembolsos)
$balance = $analyticsService->balanceValues($transactions);

// Receita mensal
$monthlyRevenue = $analyticsService->overMonths(12);

// Exibir no dashboard
return view('market::master.analytics', [
    'revenue' => $balance['income'],
    'refunds' => $balance['refunds'],
    'profit' => $balance['income'] - $balance['refunds'],
    'chart_data' => $monthlyRevenue,
]);
```

---

🔧 Uso Prático
-------------

[](#-uso-prático)

### Integração em Aplicação Laravel Existente

[](#integração-em-aplicação-laravel-existente)

#### 1. Adicionar Rotas Personalizadas

[](#1-adicionar-rotas-personalizadas)

```
// routes/web.php

use Market\Http\Controllers\ProductController;
use Market\Http\Controllers\CartController;
use Market\Http\Controllers\CheckoutController;

// Vitrine pública
Route::get('/loja', [ProductController::class, 'index']);
Route::get('/loja/produto/{url}', [ProductController::class, 'show']);

// Carrinho
Route::middleware('auth')->group(function () {
    Route::get('/carrinho', [CartController::class, 'index']);
    Route::post('/carrinho/adicionar', [CartController::class, 'add']);

    // Checkout
    Route::get('/finalizar', [CheckoutController::class, 'confirm']);
    Route::post('/processar-pagamento', [CheckoutController::class, 'process']);
});
```

#### 2. Customizar Views

[](#2-customizar-views)

```
// Publicar views
php artisan vendor:publish --tag=sitec-views

// Customizar: resources/views/vendor/market/products/show.blade.php
@extends('layouts.app')

@section('content')

    {{ $product->name }}
    R$ {{ number_format($product->price, 2, ',', '.') }}

    @if($product->variants->count())

            @foreach($product->variants as $variant)

                    {{ $variant->value }}

            @endforeach

    @endif

        Adicionar ao Carrinho

@endsection
```

#### 3. Criar Middleware Personalizado

[](#3-criar-middleware-personalizado)

```
// app/Http/Middleware/CheckProductAvailability.php

namespace App\Http\Middleware;

use Closure;
use Market\Models\Product;

class CheckProductAvailability
{
    public function handle($request, Closure $next)
    {
        $product = Product::find($request->route('id'));

        if (!$product || !$product->is_available) {
            return redirect('/loja')->with('error', 'Produto indisponível');
        }

        return $next($request);
    }
}
```

### Exemplo: Integração com Gateway de Pagamento

[](#exemplo-integração-com-gateway-de-pagamento)

```
// app/Services/CustomPaymentService.php

namespace App\Services;

use Market\Services\PaymentService as BasePaymentService;
use Market\Services\OrderService;
use Market\Services\TransactionService;

class CustomPaymentService extends BasePaymentService
{
    public function processWithPix($user, $cart)
    {
        // 1. Gerar QR Code PIX
        $pixData = $this->pixGateway->generateQRCode([
            'amount' => $cart->total(),
            'description' => 'Pedido #' . uniqid(),
        ]);

        // 2. Criar transação pendente
        $transaction = $this->transactionService->create([
            'user_id' => $user->id,
            'provider' => 'pix',
            'provider_id' => $pixData['id'],
            'state' => 'pending',
            'amount' => $cart->total(),
        ]);

        // 3. Criar pedido aguardando pagamento
        $order = $this->createOrder($user, $transaction, $cart);

        return [
            'order' => $order,
            'pix_qrcode' => $pixData['qrcode'],
            'pix_string' => $pixData['emv'],
        ];
    }
}
```

### Exemplo: Webhook para Confirmação de Pagamento

[](#exemplo-webhook-para-confirmação-de-pagamento)

```
// routes/api.php
Route::post('/webhook/payment-confirmation', [WebhookController::class, 'handle']);

// app/Http/Controllers/WebhookController.php
namespace App\Http\Controllers;

use Market\Services\OrderService;
use Market\Services\TransactionService;
use Market\Services\LogisticService;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $signature = $request->header('X-Webhook-Signature');

        // Validar assinatura
        if (!$this->validateSignature($signature, $request->getContent())) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }

        $data = $request->json()->all();

        if ($data['event'] === 'payment.approved') {
            $transaction = app(TransactionService::class)
                ->findByProviderId($data['payment_id']);

            // Atualizar transação
            $transaction->update(['state' => 'approved']);

            // Atualizar pedido
            $order = $transaction->order;
            $order->update(['status' => 'complete']);

            // Processar logística
            app(LogisticService::class)->afterPurchase($order);

            return response()->json(['status' => 'processed']);
        }

        return response()->json(['status' => 'ignored']);
    }
}
```

---

🔗 Integração com o Ecossistema SierraTecnologia
-----------------------------------------------

[](#-integração-com-o-ecossistema-sierratecnologia)

### Comunicação entre Pacotes

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

#### 1. Payment-Laravel (Gateway de Pagamento)

[](#1-payment-laravel-gateway-de-pagamento)

```
// O Market depende do Payment-Laravel para processar pagamentos

// Criar customer no gateway
$user->meta->createAsSierraTecnologiaCustomer($cardToken);

// Cobrar valor
$charge = $user->meta->charge($amount, $cardToken);

// Cobrar com último cartão salvo
$charge = $user->meta->chargeWithLastCard($amount);

// Reembolsar
$refund = $user->meta->refund($chargeId, $amount);

// Criar assinatura
$subscription = $user->meta->newSubscription('plan-name', $planId)
    ->trialDays(7)
    ->create($cardToken);
```

#### 2. Media-Manager (Gestão de Imagens)

[](#2-media-manager-gestão-de-imagens)

```
use SierraTecnologia\MediaManager\Models\Image;

// Associar imagens a produtos
$product->images()->create([
    'path' => '/storage/products/notebook-1.jpg',
    'alt' => 'Notebook Dell XPS 15',
    'title' => 'Imagem principal',
]);

// Recuperar imagens
$images = $product->images;

// Hero image (imagem principal)
$product->update([
    'hero_image' => '/storage/products/hero.jpg'
]);
```

#### 3. Pedreiro (Admin Scaffolding)

[](#3-pedreiro-admin-scaffolding)

O Market registra automaticamente itens de menu no painel admin:

```
// Em MarketProvider@boot()
$menuItens = [
    'Commerce' => [
        'Produtos' => [
            'icon' => 'pe-7s-cart',
            'route' => 'admin.market.products.index',
        ],
        'Pedidos' => [
            'icon' => 'pe-7s-note2',
            'route' => 'master.market.orders.index',
        ],
        'Transações' => [
            'icon' => 'pe-7s-cash',
            'route' => 'master.market.transactions.index',
        ],
    ],
];

event(new \Pedreiro\Events\MenuRegistered($menuItens));
```

#### 4. Crypto (Criptografia e UUID)

[](#4-crypto-criptografia-e-uuid)

```
use function SierraTecnologia\Crypto\crypto_encrypt;
use function SierraTecnologia\Crypto\crypto_decrypt;

// Gerar UUID para transações
$transaction->uuid = \Ramsey\Uuid\Uuid::uuid4()->toString();

// Criptografar IDs sensíveis em URLs
$encryptedId = crypto_encrypt($order->id);
$url = route('order.show', $encryptedId);

// Descriptografar
$orderId = crypto_decrypt($request->route('id'));
```

#### 5. Locaravel (Localização)

[](#5-locaravel-localização)

```
use function SierraTecnologia\Locaravel\RiCaService;

// Converter nome de produto para URL slug
$product->url = RiCaService::convertToURL($product->name);
// "Notebook Dell XPS 15" → "notebook-dell-xps-15"
```

### Padrões de Versionamento, Testes e CI/CD

[](#padrões-de-versionamento-testes-e-cicd)

#### Versionamento Semântico

[](#versionamento-semântico)

O Market segue **Semantic Versioning 2.0**:

- **MAJOR** (0.x.x → 1.0.0): Breaking changes
- **MINOR** (0.4.x → 0.5.0): Novas funcionalidades (backward-compatible)
- **PATCH** (0.4.4 → 0.4.5): Bug fixes

#### Estratégia de Branches (Git Flow)

[](#estratégia-de-branches-git-flow)

```
main (production)
  └── develop (integration)
       ├── feature/cart-improvements
       ├── feature/pix-integration
       └── bugfix/checkout-validation

```

### Aplicação em Ambientes de Microserviços

[](#aplicação-em-ambientes-de-microserviços)

O Market pode ser usado em arquitetura de microserviços:

```
┌─────────────────────────────────────────┐
│   API Gateway (Laravel + Market)        │
│   - Endpoints REST                      │
│   - Autenticação JWT                    │
└─────────────────┬───────────────────────┘
                  │
      ┌───────────┴───────────┐
      │                       │
┌─────▼──────┐       ┌────────▼────────┐
│  Product   │       │   Order Service │
│  Service   │       │   (Market Core) │
│  (Market)  │       └─────────────────┘
└────────────┘

```

**Exemplo de API REST**:

```
// routes/api.php
Route::prefix('v1')->middleware('auth:sanctum')->group(function () {

    // Produtos
    Route::get('/products', [Api\ProductController::class, 'index']);
    Route::get('/products/{id}', [Api\ProductController::class, 'show']);

    // Carrinho
    Route::get('/cart', [Api\CartController::class, 'index']);
    Route::post('/cart', [Api\CartController::class, 'add']);
    Route::delete('/cart/{id}', [Api\CartController::class, 'remove']);

    // Pedidos
    Route::get('/orders', [Api\OrderController::class, 'index']);
    Route::get('/orders/{uuid}', [Api\OrderController::class, 'show']);
    Route::post('/orders', [Api\OrderController::class, 'create']);
});
```

---

🎨 Extensão e Customização
-------------------------

[](#-extensão-e-customização)

### Criar Novos Módulos (Ex: Promoções)

[](#criar-novos-módulos-ex-promoções)

#### 1. Criar Model

[](#1-criar-model)

```
// app/Models/Promotion.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Market\Models\Product;

class Promotion extends Model
{
    protected $fillable = [
        'name',
        'discount_percentage',
        'start_date',
        'end_date',
        'active',
    ];

    protected $casts = [
        'start_date' => 'datetime',
        'end_date' => 'datetime',
    ];

    public function products()
    {
        return $this->belongsToMany(Product::class);
    }

    public function isActive()
    {
        return $this->active
            && now()->between($this->start_date, $this->end_date);
    }
}
```

#### 2. Criar Migration

[](#2-criar-migration)

```
// database/migrations/2024_xx_xx_create_promotions_table.php
public function up()
{
    Schema::create('promotions', function (Blueprint $table) {
        $table->id();
        $table->string('name');
        $table->integer('discount_percentage');
        $table->timestamp('start_date');
        $table->timestamp('end_date');
        $table->boolean('active')->default(true);
        $table->timestamps();
    });

    Schema::create('product_promotion', function (Blueprint $table) {
        $table->foreignId('product_id')->constrained()->onDelete('cascade');
        $table->foreignId('promotion_id')->constrained()->onDelete('cascade');
        $table->primary(['product_id', 'promotion_id']);
    });
}
```

#### 3. Estender ProductService

[](#3-estender-productservice)

```
// app/Services/PromotionService.php
namespace App\Services;

use Market\Services\ProductService;
use App\Models\Promotion;

class PromotionService
{
    protected $productService;

    public function __construct(ProductService $productService)
    {
        $this->productService = $productService;
    }

    public function applyPromotion(Promotion $promotion, $products)
    {
        foreach ($products as $product) {
            $promotion->products()->attach($product->id);
        }
    }

    public function getPromotionalPrice($product)
    {
        $promotion = $product->promotions()
            ->where('active', true)
            ->where('start_date', '=', now())
            ->first();

        if ($promotion) {
            return $product->price * (1 - $promotion->discount_percentage / 100);
        }

        return $product->price;
    }
}
```

### Substituir Classes Padrão via Injeção de Dependência

[](#substituir-classes-padrão-via-injeção-de-dependência)

```
// app/Providers/AppServiceProvider.php

use Market\Services\PaymentService;
use App\Services\CustomPaymentService;

public function register()
{
    // Substituir PaymentService por implementação customizada
    $this->app->bind(PaymentService::class, CustomPaymentService::class);
}
```

### Boas Práticas para Evitar Breaking Changes

[](#boas-práticas-para-evitar-breaking-changes)

1. **Nunca modifique arquivos do vendor/**: Use inheritance ou DI
2. **Publique e customize views**: `vendor:publish --tag=sitec-views`
3. **Use eventos e listeners**: Para adicionar lógica sem alterar código core
4. **Crie observers customizados**: Para estender comportamento de models

```
// app/Observers/ProductObserver.php
namespace App\Observers;

use Market\Models\Product;

class ProductObserver
{
    public function created(Product $product)
    {
        // Enviar email para admin
        \Mail::to('admin@loja.com')->send(new ProductCreatedMail($product));

        // Invalidar cache
        \Cache::forget('featured-products');
    }
}

// Registrar em AppServiceProvider
use Market\Models\Product;
use App\Observers\ProductObserver;

public function boot()
{
    Product::observe(ProductObserver::class);
}
```

---

💼 Exemplos Reais
----------------

[](#-exemplos-reais)

### Caso de Uso: Marketplace Multi-Vendor

[](#caso-de-uso-marketplace-multi-vendor)

```
// 1. Adicionar campo vendor_id aos produtos
Schema::table('products', function (Blueprint $table) {
    $table->foreignId('vendor_id')->nullable()->constrained('users');
});

// 2. Criar filtro por vendor
$vendorProducts = app(ProductService::class)->paginated([
    'vendor_id' => $vendorId
]);

// 3. Comissão automática no checkout
public function afterPurchase($order)
{
    foreach ($order->items as $item) {
        $product = $item->product;
        $vendor = $product->vendor;

        $commission = $item->total * 0.85; // 85% para o vendor

        VendorPayout::create([
            'vendor_id' => $vendor->id,
            'order_item_id' => $item->id,
            'amount' => $commission,
        ]);
    }
}
```

### Caso de Uso: Produtos Digitais (Downloads)

[](#caso-de-uso-produtos-digitais-downloads)

```
// 1. Criar rota de download protegida
Route::get('/download/{order}/{item}', [DownloadController::class, 'download'])
    ->middleware('auth');

// 2. Controller de download
public function download(Order $order, OrderItem $item)
{
    // Verificar se o pedido pertence ao usuário
    if ($order->user_id !== auth()->id()) {
        abort(403);
    }

    // Verificar se o item tem arquivo digital
    if (!$item->product->file) {
        abort(404, 'Arquivo não encontrado');
    }

    // Registrar download
    DownloadLog::create([
        'user_id' => auth()->id(),
        'product_id' => $item->product_id,
        'ip' => request()->ip(),
    ]);

    // Forçar download
    return Storage::download($item->product->file);
}
```

### Caso de Uso: Assinatura com Conteúdo Exclusivo

[](#caso-de-uso-assinatura-com-conteúdo-exclusivo)

```
// Middleware para verificar assinatura
public function handle($request, Closure $next)
{
    if (!auth()->user()->meta->subscribed('Premium')) {
        return redirect('/planos')->with('error', 'Assine o plano Premium para acessar');
    }

    return $next($request);
}

// Usar em rotas
Route::middleware(['auth', 'subscription:Premium'])->group(function () {
    Route::get('/cursos-exclusivos', [CourseController::class, 'index']);
});
```

### Demonstração: Antes e Depois

[](#demonstração-antes-e-depois)

**ANTES (sem Market):**

```
// Código espaguete misturado no controller
public function checkout(Request $request)
{
    $cart = Session::get('cart');
    $total = 0;
    foreach ($cart as $item) {
        $total += $item['price'] * $item['qty'];
    }

    $charge = \Stripe\Charge::create([
        'amount' => $total * 100,
        'currency' => 'brl',
        'source' => $request->token,
    ]);

    DB::table('orders')->insert([
        'user_id' => auth()->id(),
        'total' => $total,
        'created_at' => now(),
    ]);

    Session::forget('cart');

    return redirect('/success');
}
```

**DEPOIS (com Market):**

```
// Código limpo, testável e reutilizável
public function checkout(Request $request)
{
    $order = app(PaymentService::class)->purchase(
        auth()->user(),
        $request->input('card_token'),
        app(CartService::class)->getCart()
    );

    return redirect()->route('order.complete', $order->uuid);
}
```

**Benefícios:**

- ✅ 90% menos código
- ✅ Transações atômicas (rollback automático)
- ✅ Validação centralizada
- ✅ Logs automáticos
- ✅ Facilidade de teste unitário
- ✅ Reutilizável em múltiplos projetos

---

🧪 Testes e Qualidade
--------------------

[](#-testes-e-qualidade)

### Executar Testes Localmente

[](#executar-testes-localmente)

```
# Testes unitários e de integração
composer test
# ou
vendor/bin/phpunit

# Testes com cobertura
composer test-coverage
```

### Análise Estática

[](#análise-estática)

```
# PHPStan (nível 8)
vendor/bin/phpstan analyse src/

# Psalm
composer psalm
# ou
vendor/bin/psalm
```

### Verificação de Código (Code Style)

[](#verificação-de-código-code-style)

```
# PHPCS (PSR-12)
vendor/bin/phpcs --standard=PSR12 src/

# PHP CS Fixer (correção automática)
composer format
# ou
vendor/bin/php-cs-fixer fix --allow-risky=yes
```

### PHPMD (Mess Detector)

[](#phpmd-mess-detector)

```
vendor/bin/phpmd src/ text cleancode,codesize,controversial,design,naming,unusedcode
```

---

🤝 Guia de Contribuição
----------------------

[](#-guia-de-contribuição)

### Como Contribuir

[](#como-contribuir)

1. **Fork** o repositório
2. Crie uma **branch** para sua feature (`git checkout -b feature/nova-funcionalidade`)
3. **Commit** suas mudanças (`git commit -m 'feat: adiciona nova funcionalidade'`)
4. **Push** para a branch (`git push origin feature/nova-funcionalidade`)
5. Abra um **Pull Request**

### Padrões de Commits

[](#padrões-de-commits)

Seguimos o [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: adiciona suporte a pagamento via PIX
fix: corrige cálculo de frete para produtos pesados
docs: atualiza README com exemplos de uso
style: formata código conforme PSR-12
refactor: reorganiza services em subdiretórios
test: adiciona testes para ProductService
chore: atualiza dependências do composer

```

### Padrões de Branches

[](#padrões-de-branches)

- `main`: Branch de produção (somente merges via PR)
- `develop`: Branch de desenvolvimento (integração)
- `feature/nome-da-feature`: Novas funcionalidades
- `bugfix/nome-do-bug`: Correções de bugs
- `hotfix/nome-do-hotfix`: Correções urgentes em produção

### Política de Licença e Contato

[](#política-de-licença-e-contato)

- **Licença**: MIT (veja [LICENSE](LICENSE))
- **Email**:
- **Chat**: [Slack da SierraTecnologia](https://bit.ly/sierratecnologia-slack)
- **Twitter**: [@sierratecnologia](https://twitter.com/sierratecnologia)

---

📝 Changelog
-----------

[](#-changelog)

Consulte o [CHANGELOG.md](CHANGELOG.md) para histórico completo de versões.

---

💬 Suporte
---------

[](#-suporte)

Os seguintes canais de suporte estão disponíveis:

- [Chat no Slack](https://bit.ly/sierratecnologia-slack)
- [Email de Ajuda](mailto:help@sierratecnologia.com.br)
- [Siga no Twitter](https://twitter.com/sierratecnologia)
- [Issues no GitHub](https://github.com/sierratecnologia/market/issues)

---

🔐 Vulnerabilidades de Segurança
-------------------------------

[](#-vulnerabilidades-de-segurança)

Se você descobrir uma vulnerabilidade de segurança neste projeto, envie um e-mail para . Todas as vulnerabilidades serão prontamente tratadas.

---

About SierraTecnologia
----------------------

[](#about-sierratecnologia)

SierraTecnologia is a software solutions startup, specialized in integrated enterprise solutions for SMEs established in Rio de Janeiro, Brazil since June 2008. We believe that our drive The Value, The Reach, and The Impact is what differentiates us and unleash the endless possibilities of our philosophy through the power of software. We like to call it Innovation At The Speed Of Life. That’s how we do our share of advancing humanity.

License
-------

[](#license)

This software is released under [The MIT License (MIT)](LICENSE).

(c) 2008-2020 SierraTecnologia, Some rights reserved.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance47

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 99% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~69 days

Recently: every ~299 days

Total

19

Last Release

848d ago

PHP version history (3 changes)0.1.0PHP >=7.0

0.5.x-devPHP ^7.4

0.4.3PHP ^7.2|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/c0a11577f9e4f7db7533432c22786439b3155ec7bc06be9760be7260c4ce1e0d?d=identicon)[ricardosierra](/maintainers/ricardosierra)

---

Top Contributors

[![ricardosierra](https://avatars.githubusercontent.com/u/5499444?v=4)](https://github.com/ricardosierra "ricardosierra (97 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (1 commits)")

---

Tags

marketSierraTecnologia

### Embed Badge

![Health badge](/badges/sierratecnologia-market/health.svg)

```
[![Health](https://phpackages.com/badges/sierratecnologia-market/health.svg)](https://phpackages.com/packages/sierratecnologia-market)
```

###  Alternatives

[ccxt/ccxt

A cryptocurrency trading API with more than 100 exchanges in JavaScript / TypeScript / Python / C# / PHP / Go

41.5k328.9k1](/packages/ccxt-ccxt)[bukashk0zzz/yml-generator

YML (Yandex Market Language) file generator

116186.3k](/packages/bukashk0zzz-yml-generator)[lireincore/ymlparser

YML (Yandex Market Language) parser

2429.6k1](/packages/lireincore-ymlparser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)