---
id: traits-e-helpers
title: Traits e helpers
description: Comportamentos reutilizáveis e formatações compartilhadas no código do James.
type: development
status: observed
visibility: public
tags: desenvolvimento, php, convenções
related: arquitetura, contribuicao, contatos
source_refs: https://github.com/james-suite/james/tree/master/app/Traits, https://github.com/james-suite/james/tree/master/app/Helpers, https://github.com/james-suite/james/blob/master/resources/views/components/markdown.blade.php
---

No desenvolvimento do James, adotamos o uso extensivo de **Traits** e **Helpers** para manter os modelos e controllers limpos, reaproveitando lógicas e padronizando formatações.

## Traits

As Traits injetam comportamentos padronizados em modelos e controllers Eloquent que as implementam.

### `Searchable`
**Local:** `app/Traits/Searchable.php`

Esta trait adiciona o escopo estático `search($term)` aos modelos. Ela busca em tempo real por um termo específico cruzando colunas normais (via `ILIKE`) e também colunas dinâmicas `JSONB`, extraindo valores aninhados usando `jsonpath`.
Isso permite que, por exemplo, o módulo de Contatos encontre facilmente um registro digitando apenas parte do número de telefone armazenado num array dinâmico.

### `HasInitials`
**Local:** `app/Traits/HasInitials.php`

Adiciona o método `getInitials()` ao modelo que extrai e formata as iniciais baseadas na propriedade `name`. Muito útil para renderizar avatares genéricos (fallback) quando o usuário ou contato não possui uma foto (ex: "Arthur Willers" → "AW", "João" → "J").

### `HandlesAttachments`
**Local:** `app/Traits/HandlesAttachments.php`

Padroniza a sincronização de arquivos anexos (adicionando novos uploads e expurgando arquivos marcados para remoção) via Spatie MediaLibrary:
- `syncAttachments(Model $model, array $data, string $collection = 'attachments'): void`

---

## Helpers

Classes com métodos estáticos utilitários e funções globais associadas para uso direto no backend e nas views Blade.

### `DateHelper`
**Local:** `app/Helpers/DateHelper.php`

Centraliza a formatação de datas e horas usando a biblioteca `Carbon`, garantindo a aplicação do timezone configurado (`America/Sao_Paulo`):

* `formatDate($date)` / `DateHelper::format($date)`: Formato longo por extenso (Ex: `17 de Junho de 2026`).
* `formatShort($date)` / `DateHelper::formatShort($date)`: Formato numérico curto (Ex: `17/06/2026`).
* `formatDateTime($date)` / `DateHelper::formatDateTime($date)`: Formato com data e hora (Ex: `17/06/2026 às 15:42`).
* `formatRelative($date)` / `DateHelper::formatRelative($date)`: Formato amigável e relativo ao momento atual (Ex: `há 2 horas`, `em 3 dias`).
* `formatMonthYear($date)` / `DateHelper::formatMonthYear($date)`: Mês e ano abreviado (Ex: `06/2026`).
* `formatMonthYearFull($date)` / `DateHelper::formatMonthYearFull($date)`: Mês por extenso e ano em TitleCase (Ex: `Junho 2026`).

### `CurrencyHelper`
**Local:** `app/Helpers/CurrencyHelper.php`

Centraliza a formatação monetária utilizando a classe `Number::currency()` nativa do Laravel:

* `formatCurrency($value, $currency = '', $locale = null)` / `CurrencyHelper::format($value, ...)`: Converte valores numéricos em strings formatadas no padrão da moeda local (Ex: `formatCurrency(1250.50)` → `R$ 1.250,50`).

---

## Componente de Markdown Seguro

### `<x-markdown>`
**Local:** `resources/views/components/markdown.blade.php`

Renderiza conteúdo em Markdown informado por usuários, como as notas de contatos e grupos, usando a configuração segura do CommonMark. Links inseguros não são permitidos e links para domínios externos são abertos em uma nova janela. Links do próprio domínio configurado para a aplicação continuam no mesmo contexto.

Use o componente em vez de renderizar `markdown()` diretamente em uma view:

```blade
<x-markdown :content="$contact->notes" />
```