Storage Examples

<?php
/**
 * Exemplos de uso da classe Storage v2.0
 *
 * Configuração inicial: estenda a classe e defina as credenciais
 */

class DB extends Storage {
    public $hostname = 'localhost';
    public $username = 'root';
    public $password = 'senha';
    public $database = 'minha_base';
    public $encoding = 'utf8mb4';
}

$db = new DB();

// =============================================================================
// 1. prepare() — Query segura com prepared statement
//    Use sempre que a query receber dados externos (formulários, URLs etc.)
// =============================================================================

// Busca com dado vindo de fora (sem risco de SQL injection)
$email = $_POST['email'] ?? '[email protected]';

$user = $db->prepare(
    "SELECT * FROM users WHERE email = ? AND active = ?",
    [$email, 1],
    'si'
)->fetch_one();

if ($user) {
    echo "Bem-vindo, {$user['name']}!\n";
}

// Inserção segura com prepare()
$db->prepare(
    "INSERT INTO users (name, email, created_at) VALUES (?, ?, NOW())",
    ['Ana Silva', '[email protected]']
);

echo "Usuário inserido com ID: " . $db->insert_id() . "\n";


// =============================================================================
// 2. escape() — Escapar strings para uso manual em queries
//    Use quando não puder usar prepare(), como em queries dinâmicas complexas
// =============================================================================

$nome  = $db->escape($_GET['nome'] ?? '');
$ordem = in_array($_GET['ordem'] ?? '', ['ASC', 'DESC']) ? $_GET['ordem'] : 'ASC';

$db->query("SELECT * FROM products WHERE name LIKE '%{$nome}%' ORDER BY name {$ordem}");

$products = $db->fetch_assoc();
echo "Produtos encontrados: " . count($products) . "\n";


// =============================================================================
// 3. insert_array() — Inserção via array associativo
//    Campos vazios ou null viram NULL no banco
// =============================================================================

$db->insert_array('orders', [
    'user_id'    => 42,
    'product_id' => 7,
    'quantity'   => 3,
    'note'       => '',        // vira NULL automaticamente
    'created_at' => date('Y-m-d H:i:s'),
]);

$order_id = $db->insert_id();
echo "Pedido criado: #{$order_id}\n";


// =============================================================================
// 4. update_array() — Atualização via array associativo
//    O WHERE é obrigatório — lança exceção se omitido
// =============================================================================

$db->update_array('users', [
    'name'       => 'Ana Costa',
    'updated_at' => date('Y-m-d H:i:s'),
], "id = 15");

echo "Linhas atualizadas: " . $db->affected_rows() . "\n";


// =============================================================================
// 5. delete_where() — Exclusão com WHERE obrigatório
//    Segurança: não permite apagar todos os registros por engano
// =============================================================================

$db->delete_where('sessions', "expires_at < NOW()");
echo "Sessões expiradas removidas: " . $db->affected_rows() . "\n";

// Tentativa sem WHERE lança exceção:
try {
    $db->delete_where('logs', '');
} catch (InvalidArgumentException $e) {
    echo "Erro esperado: {$e->getMessage()}\n";
}


// =============================================================================
// 6. fetch_one() — Primeiro resultado como array associativo
//    Ideal quando você espera apenas um registro
// =============================================================================

$product = $db->query("SELECT * FROM products WHERE id = 12")->fetch_one();

if ($product) {
    echo "Produto: {$product['name']} — R$ {$product['price']}\n";
} else {
    echo "Produto não encontrado.\n";
}


// =============================================================================
// 7. fetch_value() — Valor de uma única coluna
//    Útil para COUNT, SUM, buscar um campo específico etc.
// =============================================================================

// Primeira coluna (índice 0)
$total_users = $db->query("SELECT COUNT(*) FROM users")->fetch_value();
echo "Total de usuários: {$total_users}\n";

// Coluna pelo nome
$email_admin = $db->query("SELECT email FROM users WHERE role = 'admin' LIMIT 1")
                   ->fetch_value('email');
echo "E-mail do admin: {$email_admin}\n";

// Soma de valores
$receita = $db->query("SELECT SUM(total) FROM orders WHERE status = 'paid'")
              ->fetch_value();
echo "Receita total: R$ " . number_format($receita, 2, ',', '.') . "\n";


// =============================================================================
// 8. count() — Contagem direta de registros
// =============================================================================

$total    = $db->count('users');
$ativos   = $db->count('users', "active = 1");
$admins   = $db->count('users', "role = 'admin'");

echo "Total: {$total} | Ativos: {$ativos} | Admins: {$admins}\n";


// =============================================================================
// 9. paginate() — Paginação automática
//    Adiciona LIMIT e OFFSET com base na página solicitada
// =============================================================================

$page     = (int) ($_GET['page'] ?? 1);
$per_page = 10;

$orders = $db->paginate(
    "SELECT o.*, u.name as user_name
     FROM orders o
     JOIN users u ON u.id = o.user_id
     ORDER BY o.created_at DESC",
    $page,
    $per_page
)->fetch_assoc();

$total_orders = $db->count('orders');
$total_pages  = ceil($total_orders / $per_page);

echo "Página {$page} de {$total_pages} ({$total_orders} pedidos no total)\n";

foreach ($orders as $order) {
    echo "  Pedido #{$order['id']} — {$order['user_name']}\n";
}


// =============================================================================
// 10. begin_transaction() / commit() / rollback() — Transações
//     Garante atomicidade: ou tudo funciona, ou nada é gravado
// =============================================================================

// Exemplo: transferência de saldo entre contas
$de_conta  = 1;
$para_conta = 2;
$valor      = 150.00;

try {
    $db->begin_transaction();

    // Verifica saldo disponível
    $saldo = $db->prepare(
        "SELECT balance FROM accounts WHERE id = ? FOR UPDATE",
        [$de_conta]
    )->fetch_value('balance');

    if ($saldo < $valor) {
        throw new RuntimeException('Saldo insuficiente.');
    }

    // Débito
    $db->prepare(
        "UPDATE accounts SET balance = balance - ? WHERE id = ?",
        [$valor, $de_conta],
        'di'
    );

    // Crédito
    $db->prepare(
        "UPDATE accounts SET balance = balance + ? WHERE id = ?",
        [$valor, $para_conta],
        'di'
    );

    // Registra a movimentação
    $db->insert_array('transactions', [
        'from_account' => $de_conta,
        'to_account'   => $para_conta,
        'amount'       => $valor,
        'created_at'   => date('Y-m-d H:i:s'),
    ]);

    $db->commit();
    echo "Transferência de R$ {$valor} realizada com sucesso.\n";

} catch (Exception $e) {
    $db->rollback();
    echo "Transferência cancelada: {$e->getMessage()}\n";
}


// =============================================================================
// 11. query_cache() / clear_cache() — Cache de resultados em memória
//     Evita repetir queries idênticas dentro da mesma requisição
// =============================================================================

// Executa e armazena em cache por 60 segundos
$config = $db->query_cache("SELECT * FROM config", 60)->fetch_assoc();
echo "Configurações carregadas: " . count($config) . " entradas\n";

// Segunda chamada usa o cache — não vai ao banco
$config_cached = $db->query_cache("SELECT * FROM config", 60)->fetch_assoc();
echo "Do cache: " . count($config_cached) . " entradas\n";

// Limpa o cache de uma query específica
$db->clear_cache("SELECT * FROM config");

// Ou limpa tudo:
$db->clear_cache();


// =============================================================================
// 12. explain() — Plano de execução da última query
//     Use para identificar queries lentas e verificar uso de índices
// =============================================================================

$db->query("SELECT * FROM orders WHERE user_id = 42 AND status = 'pending'");
$plan = $db->explain();

foreach ($plan as $row) {
    echo "Tipo: {$row['type']} | "
       . "Tabela: {$row['table']} | "
       . "Chave usada: " . ($row['key'] ?? 'nenhuma') . " | "
       . "Linhas estimadas: {$row['rows']}\n";
}

// Atenção: se 'type' for 'ALL' e 'key' for null, a query está fazendo full scan.
// Considere adicionar um índice na coluna usada no WHERE.


// =============================================================================
// 13. get_profile() — Métricas de performance de todas as queries
//     Chame no final da requisição para monitorar o desempenho geral
// =============================================================================

$metrics = $db->get_profile();

echo "\n--- Resumo da requisição ---\n";
echo "Queries executadas : {$metrics['total']}\n";
echo "Tempo total        : {$metrics['total_ms']}ms\n";
echo "Tempo médio        : {$metrics['avg_ms']}ms\n";
echo "Query mais lenta   : {$metrics['slowest']}ms\n";


// =============================================================================
// 14. get_history() — Histórico detalhado com timestamps e durações
// =============================================================================

echo "\n--- Histórico ---\n";
foreach ($db->get_history() as $i => $entry) {
    echo "#{$i} [{$entry['time']}] ({$entry['duration']}) {$entry['query']}\n";
}


// =============================================================================
// BÔNUS: is_in_transaction() — Verificar estado antes de operações críticas
// =============================================================================

if (!$db->is_in_transaction()) {
    $db->begin_transaction();
    // ... operações ...
    $db->commit();
}