Home

TBL-CLASS — Overview

TBL-CLASS é uma ferramenta CLI para PHP que gera constantes type-safe diretamente a partir do schema do banco de dados.

O objetivo é eliminar magic strings ao trabalhar com SQL, tornando o código:

• mais seguro
• mais legível
• mais previsível
• resiliente a mudanças de schema

O TBL-CLASS é ideal para APIs, frameworks customizados, aplicações modernas em PHP e pipelines CI/CD.

---

✨ Principais Características

• Geração automática de constantes PHP a partir do schema

• Constantes type-safe para:

  • tabelas
  • colunas
  • foreign keys
  • valores enum

• Detecção de alterações no schema via hash

• Compatível com MySQL, PostgreSQL e SQLite

• Interface CLI simples e previsível

• Integração nativa com Composer

• Código gerado sem dependências externas

---

📦 Instalação

composer require erilshackle/php-tbl-class --dev

Recomendado como dependência de desenvolvimento.

---

🚀 Fluxo Básico de Utilização

1. Criar o ficheiro de configuração

php vendor/bin/tbl-class

Se tblclass.yaml não existir, o comando:

1. Cria um template limpo
2. Informa o utilizador
3. Interrompe a execução

Isto garante que a configuração — especialmente o naming strategy — seja definida conscientemente.

---

2. Configurar a base de dados

database:
  driver: mysql
  host: env(DB_HOST)
  name: env(DB_NAME)
  user: env(DB_USER)
  password: env(DB_PASS)

Também é possível usar um resolver de conexão customizado via database.connection.

---

3. Gerar as classes

php vendor/bin/tbl-class

Será gerado o ficheiro Tbl.php, contendo classes organizadas por responsabilidade.

---

4. Verificar alterações no schema

php vendor/bin/tbl-class --check

Nenhum ficheiro é sobrescrito. Apenas indica se o schema mudou desde a última geração.

---

📁 Estrutura do Código Gerado

final class Tbl
{
    /** table: users */
    public const users = 'users';

    /** `users`.`id` */
    public const users__id = 'id';

    /** `users`.`email` */
    public const users__email = 'email';

    /** posts.user_id → users.id */
    public const fk__posts__users = 'user_id';

    public const enum__users__active   = 'active';
    public const enum__users__pending  = 'pending';
    public const enum__users__inactive = 'inactive';
}

final class Tbk
{
    // reservado para PK, FK e UK (futuro)
}

final class Tbe
{
    // reservado para enums (futuro)
}

---

🔧 Configuração — tblclass.yaml

enabled: true

include: null

database:
  connection: null
  driver: mysql   # mysql | pgsql | sqlite

  host: env(DB_HOST)
  port: env(DB_PORT)
  name: env(DB_NAME)
  user: env(DB_USER)
  password: env(DB_PASS)

output:
  path: "./"
  namespace: ""

  # ⚠ IMPORTANT
  # This strategy defines ALL generated constant names.
  # Changing it later WILL rename constants and MAY break code.
  #
  # Strategies:
  # - full  → users, users__email, fk__posts__users
  # - abbr  → users, usr__email, fk__posts__users
  # - alias → users, u__email, fk__posts__users
  # - upper → USERS, USERS__EMAIL, FK__POSTS__USERS
  naming:
    strategy: full

---

🧠 Naming Strategy

A naming strategy é global e afeta todas as constantes geradas:

• tabelas
• colunas
• foreign keys
• enums

Alterar a estratégia é uma breaking change e deve ser tratada como refactor.

full (default)

Tbl::users
Tbl::users__id
Tbl::fk__posts__users

abbr

Tbl::users
Tbl::usr__id
Tbl::fk__posts__users

alias

Tbl::users
Tbl::u__id
Tbl::fk__posts__users

upper

Tbl::USERS
Tbl::USERS__ID
Tbl::FK__POSTS__USERS

---

🔍 Detecção de Alterações de Schema

Cada geração inclui metadados no ficheiro:

/**
 * @schema-hash md5:abc123...
 * @generated   2026-01-08 18:42:00
 */

Se o hash mudar, o schema foi alterado.

---

📝 Exemplo de Utilização

$sql = "
    SELECT *
    FROM " . Tbl::users . "
    WHERE " . Tbl::users__id . " = ?
";

$status = Tbl::enum__users__active;
$fk     = Tbl::fk__posts__users;

---

📄 Licença

MIT License — Eril TS Carvalho

---

TBL-CLASS Type-safe database schema constants for PHP.