@extends('layouts.docs') @section('title', 'Helpers System - OG Framework') @section('body')
{{-- Floating shapes for styling --}}
{{-- Left Sidebar: Navigation --}} @include('docs.partials.sidebar') {{-- Main Content --}}
{{-- Page Header --}}
Voltar para Documentação

Core

Helpers System

O Framework OfficeGest fornece um ecossistema rico de funções auxiliares que aumentam a produtividade. Oferece funções globais e classes estáticas otimizadas para uso frequente em qualquer parte da aplicação.

{{-- Introduction --}}

Visão Geral

Os helpers encontram-se em Modules/Common/Helpers/ e dividem-se em duas categorias:

Funções Globais

Disponíveis em qualquer lugar: app(), config(), request(), route(), logger(). Não precisam de import.

Classes Estáticas

Para operações complexas: ArrayHelper, StringHelper, DataTableHelper, Response. Requerem use.

{{-- Global Functions --}}

Funções Globais

Ficheiro: Modules/Common/Helpers/Helpers.php. Estas funções estão disponíveis em Controllers, Views, Classes, etc.

{{-- Application & Config --}}

Aplicação e Configuração 

// app() - Acede ao Service Container (Injeção de Dependência)
$container = app();
$service = app(ConfigurationService::class);

// config() - Obtém configuração com "dot notation"
$debug = config('app.debug');
$timezone = config('app.timezone', 'UTC'); // Com valor default

// envVar() - Variáveis de ambiente com tipagem inteligente
// Converte "true"/"false" strings para booleanos reais
$debug = envVar('APP_DEBUG', false);
{{-- Strings & Arrays --}}

Strings e Arrays

Conversão de Case

snakeCase('fooBar');   // 'foo_bar'
camelCase('foo_bar');  // 'fooBar'
kebabCase('fooBar');   // 'foo-bar'
studlyCase('foo_bar'); // 'FooBar'
titleCase('a new title'); // 'A New Title'

Validação e Encoding

isJson($payload);      // Valida JSON
randomString(32);      // Token alfanumérico
forceBoolean('true');  // Converte para bool
utf8Encode($legacy);   // ISO-8859-1 -> UTF-8
{{-- URLs & Routes --}}

URLs e Rotas 

// route() - Gera URLs para rotas nomeadas
// ESSENCIAL para manter a aplicação desacoplada de URLs hardcoded
$url = route('users.edit', ['id' => 1]);

// websiteUrl() - URLs absolutas para assets públicos
$logo = websiteUrl('img/logo.png');

// sanitizeUrl() - Limpa e valida URLs
$clean = sanitizeUrl('www.google.com'); // 'http://www.google.com'
{{-- HTTP & Responses --}}

HTTP e Responses 

// request() - Acede ao Request atual
$request = request();
$name = request('name', 'Guest');

// response() - Cria resposta HTTP fluente
return response('Hello', 200, ['X-Custom' => 'Value']);

// abort() e variantes condicionais
abort(403, 'Forbidden');
abortIf(!Auth::user()->isAdmin(), 403);
abortUnless(Auth::check(), 401);

// csrf_token() - Token CSRF da sessão
<input type="hidden" name="_token" value="<?= csrf_token() ?>">
{{-- Debug & Logging --}}

Debug e Logging 

// logger() - Instância Monolog
logger()->info('Job started');

// loggerBatch() - Múltiplas entradas de uma só vez
// Útil para não "bombardear" o disco com múltiplas escritas
loggerBatch('error', 'Error occurred', ['ctx' => $data]);

// requestDebugger() - Despeja estado completo do request
// Extremamente útil para debugar webhooks de terceiros
requestDebugger();
{{-- ArrayHelper --}}

ArrayHelper

Classe: Og\Modules\Common\Helpers\ArrayHelper
Uma "Powerhouse" para manipulação de dados complexos com suporte completo a Dot Notation.

{{-- Dot Notation --}}

Dot Notation (Acesso Profundo) 

use Og\Modules\Common\Helpers\ArrayHelper;

$data = ['users' => ['john' => ['role' => 'admin']]];

// get() - Recupera valores aninhados com segurança
$role = ArrayHelper::get($data, 'users.john.role'); // 'admin'
$missing = ArrayHelper::get($data, 'users.pete.role', 'guest'); // 'guest'

// set() - Define valores em profundidade, criando estrutura
$data = [];
ArrayHelper::set($data, 'system.settings.dark_mode', true);
// Resultado: ['system' => ['settings' => ['dark_mode' => true]]]

Wildcards com dotSearch() 

$users = [
    ['id' => 1, 'name' => 'Ana', 'meta' => ['active' => true]],
    ['id' => 2, 'name' => 'Rui', 'meta' => ['active' => false]],
];

// Obter todos os nomes
$names = ArrayHelper::dotSearch('*.name', $users); // ['Ana', 'Rui']

// Obter status de todos
$actives = ArrayHelper::dotSearch('*.meta.active', $users); // [true, false]
{{-- Transformations --}}

Transformações

dot() e undot()

// Achata array em chaves com ponto
ArrayHelper::dot(['a' => ['b' => 'c']]);
// ['a.b' => 'c']

// Reverte o processo
ArrayHelper::undot(['a.b' => 'c']);
// ['a' => ['b' => 'c']]

map() e flatten()

// Map que preserva chaves
ArrayHelper::map($users, fn($u) => $u['name']);

// Achata multidimensional
ArrayHelper::flatten([1, [2, 3], [[4]]]);
// [1, 2, 3, 4]
{{-- Filtering --}}

Filtragem e Pesquisa 

// where() - Filtra mantendo apenas matches
$adults = ArrayHelper::where($users, fn($u) => $u['age'] >= 18);

// firstWhere() - Primeiro elemento que satisfaz condição
$admin = ArrayHelper::firstWhere($users, fn($u) => $u['role'] === 'admin');

// only() e except() - Subconjuntos de chaves
$publicData = ArrayHelper::except($userData, ['password', 'token']);
$minimal = ArrayHelper::only($userData, ['id', 'name']);

// pluck() - Extrai lista de valores de uma chave
$ids = ArrayHelper::pluck($users, 'id'); // [1, 2]
{{-- StringHelper --}}

StringHelper

Classe: Og\Modules\Common\Helpers\StringHelper
Utilitários para manipulação avançada de strings.

Conversão de Case

StringHelper::toSnakeCase($str);
StringHelper::toCamelCase($str);
StringHelper::toPascalCase($str);
StringHelper::toKebabCase($str);

// Detecta automaticamente o formato
StringHelper::detectCase('userName');
// 'camelCase'

Manipulação de Texto

// Slugs para URLs
StringHelper::slug('Café & Leite');
// 'cafe-leite'

// Truncar sem quebrar palavras
StringHelper::truncatePreserveWords(
    'Hello beautiful world', 10
); // "Hello..."

// Extrair apenas números
StringHelper::extractNumbers('12.50€');
// "12.50"
{{-- DataTableHelper --}}

DataTableHelper

Classe: Og\Modules\Common\Helpers\DataTableHelper
Fundamental para integração com jQuery DataTables no backoffice. Gere a "tradução" entre o request complexo do DataTables e os parâmetros que os Services esperam.

Fluxo Padrão de Uso

public function listUsers() {
    // 1. Converter request do DataTables em parâmetros padronizados
    // (page, limit, order, search, filters)
    $params = DataTableHelper::prepareParams(request()->all());

    // 2. Obter dados do Service
    $result = $this->userService->list($params);

    // 3. Devolver JSON formatado para o DataTables
    return DataTableHelper::returnToDataTable(
        draw: (int)request('draw'),
        totalLines: $result['total'],
        data: $result['data']
    );
}
{{-- Response Helper --}}

Response Helper

Classe: Og\Modules\Common\Helpers\Response
Métodos estáticos para respostas HTTP especializadas, além do helper global response().

JSON

Response::json(
    $data,
    $status = 200
);

Download

Response::download(
    $path,
    $filename
);

Stream (Large Files)

Response::streamDownload(
    $callback,
    $filename
);

JSONP (Legacy)

Response::jsonp(
    $callback,
    $data
);
{{-- Quick Reference Table --}}

Referência Rápida

Categoria Funções Principais
Container app(), config(), envVar()
Request request(), abort(), abortIf()
Response response(), route(), url()
Logging logger(), loggerBatch(), requestDebugger()
Arrays ArrayHelper::get(), ::set(), ::pluck()
Strings StringHelper::slug(), ::toSnakeCase()
{{-- Navigation --}}
Routing Cache System
{{-- Right Sidebar: Table of Contents --}} @include('docs.partials.toc', ['sections' => [ 'visao-geral' => 'Visão Geral', 'funcoes-globais' => 'Funções Globais', 'array-helper' => 'ArrayHelper', 'string-helper' => 'StringHelper', 'datatable-helper' => 'DataTableHelper', 'response-helper' => 'Response Helper', 'referencia' => 'Referência Rápida', ]])
@endsection