Update README.md

Author: erilshackle

README.md

@@ -2,15 +2,19 @@
 
 ### Type-safe database schema constants para PHP
 
-[![Latest Version](https://img.shields.io/packagist/v/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class) [![PHP Version](https://img.shields.io/packagist/php-v/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class) [![License](https://img.shields.io/packagist/l/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class) [![Downloads](https://img.shields.io/packagist/dt/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class) [![Stars](https://img.shields.io/github/stars/erilshackle/tbl-class-php?style=social)](https://github.com/erilshackle/tbl-class-php)
+[![Latest Version](https://img.shields.io/packagist/v/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class)
+[![PHP Version](https://img.shields.io/packagist/php-v/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class)
+[![License](https://img.shields.io/packagist/l/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class)
+[![Downloads](https://img.shields.io/packagist/dt/eril/tbl-class)](https://packagist.org/packages/eril/tbl-class)
+[![Stars](https://img.shields.io/github/stars/erilshackle/tbl-class-php?style=social)](https://github.com/erilshackle/tbl-class-php)
 
 ---
 
 ## O que é o tbl-class?
 
-**TBL-CLASS** é uma ferramenta **CLI para PHP** que gera **classes com constantes type-safe** directamente a partir do **esquema do seu banco de dados**.
+**TBL-CLASS** é uma ferramenta **CLI para PHP** que gera **classes com constantes type-safe** diretamente a partir do **esquema do seu banco de dados**.
 
-Permite referenciar **tabelas, colunas, foreign keys e valores enum** sem recorrer a strings mágicas, tornando o código:
+Permite referenciar **tabelas, colunas, foreign keys, joins e valores enum** sem recorrer a strings mágicas, tornando o código:
 
 * mais seguro
 * mais legível
@@ -27,7 +31,7 @@ Permite referenciar **tabelas, colunas, foreign keys e valores enum** sem recorr
 * Constantes **type-safe e centralizadas**
 * Detecção de alterações no esquema via **hash**
 * Compatível com **MySQL, PostgreSQL e SQLite**
-* Classes organizadas: `Tbl`, `TblFk`, `TblEnum`
+* Helpers de **JOIN baseados em foreign keys**
 * Interface CLI simples e previsível
 * Integração nativa com Composer
 
@@ -41,9 +45,8 @@ Exemplo:
 
 ```php
 Tbl::users
-Tbl::users_id
-TblFk::posts_users
-TblEnum::users_status_active
+Tbl::users__id
+Tbl::on__posts__users
 ```
 
 Isto garante:
@@ -86,6 +89,11 @@ database:
   user: env(DB_USER)
   password: env(DB_PASS)
 ```
+ou usando callback
+```yaml
+database:
+  connection: "class::method"
+```
 
 ---
 
@@ -97,9 +105,8 @@ php vendor/bin/tbl-class
 
 É gerado o ficheiro `Tbl.php` contendo:
 
-* `Tbl` → tabelas, colunas e aliases
-* `TblFk` → foreign keys
-* `TblEnum` → valores enum
+* `Tbl` → tabelas, colunas e JOIN helpers
+* enums e metadata de schema
 
 ---
 
@@ -111,112 +118,113 @@ php vendor/bin/tbl-class --check
 
 ---
 
-## 📁 Exemplo de Código Gerado 
+## 🔗 JOIN Helpers (v1.1.0)
+
+A partir da **v1.1.0**, o `tbl-class` gera automaticamente **helpers de JOIN** com base nas **foreign keys reais do schema**.
+
+### Constantes geradas
+
+Para uma foreign key:
+
+```
+posts.user_id → users.id
+```
+
+é gerada a constante:
 
 ```php
-<?php
+public const on__posts__users = 'posts.user_id = users.id';
+```
 
-final class Tbl
-{
-    /** table: users (alias: u) */
-    public const users = 'users';
+---
 
-    /** `users`.`id` */
-    public const users__id = 'id';
+### Uso direto
 
-    /** `users`.`email` */
-    public const users__email = 'email';
+```php
+Tbl::on__posts__users();
+// posts.user_id = users.id
+```
 
-    /** 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
-{
-  // futuramente dedicado aos PK, FK e UK
-}
+### Uso com aliases (via __callStatic)
 
-final class Tbe
-{
-  // futuramente - dedicado aos enums
-}
+```php
+Tbl::on__posts__users('p', 'u');
+// p.user_id = u.id
 ```
 
 ---
 
-## 🔧 Configuração Completa (`tblclass.yaml`)
+### Helper de alias de tabela
 
-```yaml
-include: null
+```php
+Tbl::users('u');
+// users AS u
+```
 
-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)
+### Exemplo completo de SQL
 
-  # sqlite
-  # path: env(DB_PATH)
+```php
+$sql = "
+    SELECT *
+    FROM " . Tbl::users('u') . "
+    JOIN " . Tbl::posts('p') . "
+      ON " . Tbl::on__posts__users('p', 'u') . "
+    WHERE u.status = ?
+";
+```
 
-output:
-  path: "./"
-  namespace: ""
+---
 
-  naming:
-    strategy: full # full | short | alias
+## 📁 Exemplo de Código Gerado
 
-    abbreviation:
-      max_length: 15
-      dictionary_lang: en # en | pt | es | all
-      dictionary_path: null
+```php
+final class Tbl
+{
+    /** TABLE: users */
+    public const users = 'users';
+
+    /** COLUMN: users.id */
+    public const users__id = 'id';
+
+    /** JOIN: posts.user_id = users.id */
+    public const on__posts__users = 'posts.user_id = users.id';
+
+}
 ```
 
 ---
 
 ## 🧠 Estratégias de Nomenclatura
 
-Naming strategy is global and applied consistently to tables, columns, foreign keys and enums.
-Changing the strategy is a breaking change and should be treated as a refactor.
+Naming strategy é global e aplicada consistentemente a tabelas, colunas, joins e enums.
+Alterar a estratégia é um **breaking change** e deve ser tratado como refactor.
 
 ### `full` (default)
 
 ```php
 Tbl::users
 Tbl::users__id
-Tbl::fk__users__posts
+Tbl::on__posts__users
 ```
 
-### `short` 
+### `short`
 
 ```php
-Tbl::users
+Tbl::usr
 Tbl::usr__id
-Tbl::fk__users__posts
-```
-
-### `abbr` 
-
-```php
-Tbl::users        // users
-Tbl::usr__id     // users_id
-Tbl::fk__usr_pst  // users_posts
+Tbl::on__pst__usr
 ```
->
 
-### `alias`
+### `abbr`
 
 ```php
-Tbl::users          // users
-Tbl::u__id       // users_id
-Tbl::fk__u__p      // users_posts
+Tbl::u
+Tbl::u__id
+Tbl::on__p__u
 ```
 
 ---
@@ -228,7 +236,7 @@ Cada geração inclui metadados:
 ```php
 /**
  * @schema-hash md5:abc123...
- * @generated 2026-01-08 18:42:00
+ * @generated 2026-01-25 21:10:00
  */
 ```
 
@@ -243,7 +251,7 @@ Se o hash mudar, o schema foi alterado.
 ```json
 {
   "autoload": {
-    "files": ["Tbl.php"]
+    "files": ["path/to/Tbl.php"]
   }
 }
 ```
@@ -254,7 +262,7 @@ Se o hash mudar, o schema foi alterado.
 {
   "autoload": {
     "psr-4": {
-      "App\\Database\\": "src/Database/"
+      "Tbl\\": "path/to/Tbl/"
     }
   }
 }
@@ -266,37 +274,17 @@ composer dump-autoload
 
 ---
 
-## 📝 Exemplo de Utilização
-
-```php
-$sql = "
-    SELECT *
-    FROM " . Tbl::users . "
-    WHERE " . Tbl::users_id . " = ?
-";
-
-$status = Tbl::enum__users__active;
-$fk     = Tbl::fk__posts__users;
-$alias  = Tbl::as__users;
-```
-
----
-
 ## 🐛 Resolução de Problemas
 
-**Nenhuma tabela encontrada**
-
-* Verifique a base de dados configurada
-* Confirme que existem tabelas
+**JOIN não gerado**
 
-**Erro de ligação**
+* Verifique se existe foreign key real no schema
+* Reexecute o gerador após alterações
 
-* Credenciais incorrectas no `tblclass.yaml`
-* Serviço da base de dados inactivo
-
-**Schema alterado**
+**Nenhuma tabela encontrada**
 
-* Reexecutar `tbl-class`
+* Confirme a base de dados configurada
+* Verifique permissões
 
 ---
 
@@ -309,7 +297,7 @@ MIT License — Eril TS Carvalho
 ## 🤝 Contribuições
 
 Issues e pull requests são bem-vindos.
-Sugestões técnicas são apreciadas.
+Discussões técnicas são incentivadas.
 
 ---