Tbl::class v3 — PHP Schema Constants Generator

CLI Tool that Generates PHP Table & Column Constants

Generate PHP class constants from your database schema. The generated classes provide type safety and prevent typos in table and column names at runtime.

Statically accessible constants for safety and productivity:

Tbl::users Tbl::users_email Tbl::fk_users_roles

---

Version	Install command
Stable	composer require eril/tbl-class --dev
Dev	composer require eril/tbl-class:dev-main --dev

Ideal for projects that want static, IDE-assisted safety when referencing database tables and columns.

🚀 Quick Start

# Install
composer require eril/tbl-class --dev

# Generate constants
vendor/bin/tbl-class

# Configure tblclass.yaml (auto-created on first run)

# That's it! Constants ready to use:
echo Tbl::users;          // 'users'
echo Tbl::users_email;    // 'email'
echo Tbl::fk_posts_users; // 'user_id'

---

✨ Features

• Zero runtime dependencies – development-only tool
• Multi-database support (MySQL & SQLite)
• Deterministic schema generation with consistent hashing
• CI/CD-compatible via tbl-class --check (requires an available schema)
• Simple YAML configuration
• Namespace or global constants generation
• Foreign key constant generation
• Smart naming strategies (full, abbr)
• Built-in and custom abbreviation dictionaries
• Automatic JOIN constant generation - pre-built SQL JOIN clauses
• Intelligent table aliases - automatic 1-3 letter aliases for JOINs

---

📦 Installation

# Local project
composer require eril/tbl-class --dev

# Global installation
composer global require eril/tbl-class

---

🛠️ Usage

Basic Usage

# Generate constants (creates config if missing)
tbl-class


# With custom output directory
tbl-class src/Models/

# With namespace
tbl-class --namespace="App\Models"

# Global mode - Generate global constants (tbl_constants.php)
tbl-class --global

# Check for schema changes (CI/CD)
tbl-class --check

View/Manage Configuration

setup your tblclass.yaml

# Show config file
tbl-class --config

View Logs

# Show generation logs
tbl-class-logs

# Clear logs
tbl-class-logs --clear

---

⚙️ Configuration

On first run, a tblclass.yaml file is created:

# Database configuration
database:
  # Optional custom PDO connection:
  # connection: 'App\Database::getConnection'

  driver: mysql           # mysql or sqlite
  
  # For MySQL (recommended: use environment variables):
  host: env(DB_HOST)      # or 'localhost'
  port: env(DB_PORT)      # or 3306
  name: env(DB_NAME)      # required
  user: env(DB_USER)      # or 'root'
  password: env(DB_PASS)  # or ''
  
  # For SQLite:
  # driver: sqlite
  # path: env(DB_PATH)      # or 'database.sqlite'

# Output configuration 
output:
  path: "./"              # Where to save Tbl.php
  namespace: ""           # PHP namespace (optional)
  
  # Naming strategies for constants (fullname or abbreviated)
  naming:
    table: "full"        # full, abbr
    column: "full"       # full, abbr  
    foreign_key: "abbr"  # full, abbr
    
    # Abbreviation settings
    abbreviation:
      dictionary_path: null   # custom dictionary path (relative to project)
      dictionary_lang: "en"   # 'en', 'pt', or 'all'
      max_length: 20          # max abbreviation length

You can copy it and put on your project root, filename must be "tblclass.yaml"

Connection Methods (choose one):

1. Environment Variables (recommended):

   # .env file
   DB_NAME=my_database
   DB_HOST=localhost
   DB_USER=root
   DB_PASS=

2. Direct Values in YAML (not recomended, but works):

   database:
     name: my_database
     host: localhost
     user: root
     password: ""

3. Custom PDO Callback:

   database:
     connection: 'App\Database::getConnection'

---

💡 Usage in Code

<?php
// Once generated and autoload configured:

// Use constants anywhere in your app
$query = "SELECT * FROM " . Tbl::users . 
         " WHERE " . Tbl::users_email . " = ?" .
         " AND " . Tbl::fk_posts_users . " = ?";

// Get autocomplete in your IDE
echo Tbl::products;          // 'products'
echo Tbl::products_price;    // 'price'
echo Tbl::fk_orders_users;   // 'user_id'

// Global mode (tbl_constants.php)
echo tbl_users;              // 'users'
echo tbl_fk_posts_users;     // 'user_id'

// With 'abbr' strategy (using built-in dictionary):
echo Tbl::usr;           // 'usuarios' (abbreviated)
echo Tbl::usr_email;     // 'email'
echo Tbl::fk_usr_prof;   // 'profissional_id'

// With 'full' strategy (original behavior):
echo Tbl::usuarios;      // 'usuarios'
echo Tbl::usuarios_id;   // 'id'

// NEW: Use pre-built JOIN constants
$joinQuery = "SELECT * FROM " . Tbl::as_users . 
             " JOIN " . Tbl::as_posts . 
             " ON " . Tbl::on_users_posts;
// Result: "SELECT * FROM users u JOIN posts p ON u.id = p.user_id"

// NEW: Table aliases available
echo Tbl::as_users;    // 'users u'
echo Tbl::as_posts;    // 'posts p'

Autoload Configuration:

⚠️ Required only if you are not using namespace-based autoloading. After generation, add to composer.json:

{
  "autoload": {
    "files": ["path/To/Tbl.php"]
  }
}

Then run: composer dump-autoload

---

📚 Dictionary System

Tbl-class includes built-in abbreviation dictionaries:

// example
return [
    'user' => 'usr',
    'customer' => 'cust',
    'product' => 'prod',
    // ...
];

Custom Dictionary

Create data/my_dict.php in your project:

return [
    'minha_tabela' => 'mytbl',
    'outra_tabela' => 'otbl',
];

| Then reference in config:

abbreviation:
  dictionary_path: "data/my_dict.php"

filepath can be anywhere you like in your project.

---

📊 Generated Output Example

<?php
namespace App\Models;

/**
 * Database constants for schema 'example'
 * 
 * @generated 2025-12-15 17:24:59
 * @tool      tbl-class 
 * 
 * @warning AUTO-GENERATED - DO NOT EDIT MANUALLY
 */
class Tbl
{
    // Table: users
    public const users = 'users';
    public const users_id = 'id';
    public const users_email = 'email';
    public const users_name = 'name';
    
    // Table: products
    public const products = 'products';
    public const products_id = 'id';
    public const products_price = 'price';

    // --- Aliases ---
    
+   public const as_users = 'users u';


    // --- Foreign Keys ---

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

    
   // --- Join Constants ---

   /** users → posts */
   public const on_users_posts = 'u.id = p.user_id';
}

---

🐛 Troubleshooting

Common Issues:

1. "Autoload not found"

   # Run composer install
   composer install

2. "Database name not configured"

   # Edit config file
   tbl-class --config
   # Set database.name in tblclass.yaml

3. Connection fails

   # Check your .env or config file
   # Ensure database server is running

4. "Schema changed!" on every check

   # v3.1.0+ has consistent hashing
   # Run once to initialize state:
   tbl-class
   # Then check will work correctly

• Getting Help

  # Show all options
  tbl-class --help
  tbl-class-logs --help

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

📄 License

MIT License - see LICENSE file for details.

---

🎯 Why tbl-class?

• Type Safety - Eliminate string typos in SQL queries
• IDE Autocomplete - Get instant table/column name suggestions
• Refactoring Friendly - Easy to find and update table references
• Schema Documentation - Generated class serves as schema reference
• CI/CD-compatible with tbl-class --check you can keep your Class and DB in sync
• Smart JOIN Building - Pre-generated JOIN clauses with intelligent aliases
• Consistent Aliases - Automatic 1-3 letter aliases that maintain table identity

---

Stop writing strings, start using constants! Tbl:: 🚀