Info Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require atlas/info
   

2. Set Up a Connection: Ensure you have an Atlas\Pdo\Connection instance. If using Laravel, wrap it in a service provider:

   use Atlas\Pdo\Connection;
   use Atlas\Info\Info;
   
   $connection = Connection::new(config('database.connections.mysql'));
   $info = Info::new($connection);
   

3. First Use Case: Fetch table names to verify functionality:

   $tables = $info->fetchTableNames();
   dd($tables); // Debug output
   

Where to Look First

• Documentation: Atlas.Info Docs
• Source Code: Focus on src/Info.php for the core API and src/Database/ for database-specific implementations (e.g., MysqlInfo.php, PgsqlInfo.php).
• Changelog: Review recent fixes (e.g., MariaDB issues in v1.2.1) to understand edge cases.

Implementation Patterns

Core Workflows

1. Schema Discovery:

   • Fetch Tables: Use fetchTableNames() for all tables or specify a schema:

     $tables = $info->fetchTableNames('custom_schema');
     

   • Filter System Tables: Automatically excludes views/system tables (since v1.2.0).

2. Column Introspection:

   • Fetch Columns: Get structured metadata for a table:

     $columns = $info->fetchColumns('users');
     foreach ($columns as $name => $def) {
         if ($def['primary']) {
             echo "Primary key: $name\n";
         }
     }
     

   • Use Cases:
     • Dynamic Form Generation: Build forms based on NOT NULL/default values.
     • Validation Rules: Infer Laravel validation rules from column types (e.g., type: 'integer' → rules: ['integer']).

3. Database-Specific Features:

   • PostgreSQL Auto-Increment: Fetch sequence names:

     $sequence = $info->fetchAutoincSequence('users');
     

   • MySQL ENUMs: Access options array for ENUM columns.

4. Integration with Laravel:

   • Service Provider: Register Info as a singleton:

     $this->app->singleton(Info::class, function ($app) {
         return Info::new(Connection::new(config('database.default')));
     });
     

   • Facade: Create a facade for cleaner syntax:

     // app/Facades/AtlasInfo.php
     public static function getColumns(string $table) {
         return app(Info::class)->fetchColumns($table);
     }
     

     Usage:

     $columns = AtlasInfo::getColumns('users');
     

Advanced Patterns

1. Caching Metadata:

   • Cache results to avoid repeated DB queries:

     $cacheKey = 'schema:users:columns';
     $columns = Cache::remember($cacheKey, now()->addHours(1), function () use ($info) {
         return $info->fetchColumns('users');
     });
     

2. Schema Validation:

   • Compare expected vs. actual schema (e.g., in migrations):

     $expectedColumns = ['id', 'name', 'email'];
     $actualColumns = array_keys($info->fetchColumns('users'));
     assert(array_diff($expectedColumns, $actualColumns) === [], 'Schema mismatch!');
     

3. Dynamic Query Building:

   • Build queries based on column types:

     $columns = $info->fetchColumns('products');
     $where = [];
     foreach ($columns as $name => $def) {
         if ($def['type'] === 'integer' && $def['notnull']) {
             $where[] = "$name > 0";
         }
     }
     DB::table('products')->whereRaw(implode(' AND ', $where))->get();
     

4. Migration Helpers:

   • Generate down() methods for migrations:

     $columns = $info->fetchColumns('old_table');
     foreach ($columns as $name => $def) {
         echo "Schema::table('old_table', function (Blueprint \$table) {\n";
         echo "    \$table->dropColumn('$name');\n";
         echo "});\n";
     }
     

Gotchas and Tips

Pitfalls

1. Atlas.Pdo Dependency:

   • Issue: Requires Atlas\Pdo\Connection, not native PDO.
   • Fix: If using Laravel’s PDO, create a wrapper:

     use Atlas\Pdo\Connection;
     use PDO;
     
     $pdo = DB::connection()->getPdo();
     $atlasConnection = Connection::new($pdo);
     

2. Database-Specific Quirks:

   • PostgreSQL: fetchAutoincSequence() returns null for non-PostgreSQL DBs.
   • MySQL/MariaDB: ENUM options may be missing in older versions (fixed in v1.2.1).
   • SQLite: Limited metadata support (e.g., no default values for expressions).

3. Schema Name Handling:

   • Issue: fetchTableNames('schema') may fail if the schema doesn’t exist.
   • Fix: Wrap in a try-catch or check schema existence first:

     try {
         $tables = $info->fetchTableNames('nonexistent_schema');
     } catch (\Exception $e) {
         $tables = [];
     }
     

4. Column Default Values:

   • Issue: default values for numeric types are returned as int/float, not strings (since v1.2.0).
   • Tip: Cast back to string if needed:

     $default = (string) $columns['price']['default'];
     

5. Views and System Tables:

   • Issue: fetchTableNames() excludes views/system tables (since v1.2.0), which may break existing logic.
   • Fix: Use raw SQL if you need all tables:

     $allTables = DB::select("SHOW TABLES");
     

Debugging Tips

1. Log Raw Queries:

   • Enable PDO logging to debug schema queries:

     $connection->getPdo()->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
     $connection->getPdo()->setAttribute(PDO::ATTR_STATEMENT_CLASS, [\Atlas\Pdo\Statement::class, ['logQueries' => true]]);
     

2. Verify Database Support:

   • Check if your DB is supported by inspecting Atlas\Info\Database\ classes. Add custom implementations if needed.

3. Handle NULL Defaults:

   • Some databases return NULL for SQL expressions (e.g., DEFAULT CURRENT_TIMESTAMP). Normalize defaults:

     $default = $columns['created_at']['default'] ?? 'NULL';
     

Extension Points

1. Custom Database Drivers:

   • Extend Atlas\Info\Database\InfoInterface to support unsupported DBs (e.g., SQL Server):

     class SqlServerInfo implements InfoInterface {
         public function fetchTableNames(?string $schema = null): array {
             // Custom implementation
         }
         // ... other methods
     }
     

2. Override Auto-Detection:

   • Force a specific Info class for a connection:

     $info = Info::new($connection, SqlServerInfo::class);
     

3. Add Metadata Fields:

   • Extend column definitions by subclassing (e.g., add comment field):

     $columns = $info->fetchColumns('users');
     foreach ($columns as &$column) {
         $column['comment'] = $this->fetchColumnComment('users', $column['name']);
     }
     

4. Cache Invalidation:

   • Listen to Laravel events (e.g., migrated) to clear cached schema metadata:

     Event::listen('migrated', function () {
         Cache::forget('schema:*');
     });
     

Performance Quirks

1. Avoid Frequent Calls:

   • Schema queries can be slow on large databases. Cache results aggressively:

     Cache::remember('schema:tables', now()->addHours(6), function () use ($info) {
         return $info->fetchTableNames();
     });
     

2. Batch Processing:

   • For large tables, fetch columns in batches or use LIMIT in raw queries.

3. Connection Pooling:

   • Atlas.Pdo may not reuse connections by default. Configure pooling if needed:

     $connection = Connection::new(config('database.default'), [
         'pool' => true,
     ]);