README

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):

Environment Variables (recommended):

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

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

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

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:

"Autoload not found"
```
# Run composer install
composer install
```

"Database name not configured"

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

Connection fails

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

"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

Fork the repository
Create a feature branch
Make your changes
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:: 🚀

eril / tbl-class

Maintainers

Details