docs: Improve README and add ROADMAP for future features

google-labs-jules[bot] · google-labs-jules[bot] · commit 8d053bd0b91c · 2025-05-23T13:19:02.000Z
- I enhanced README.md with a more detailed project description, prerequisites, usage clarifications for SqlDumperClass (including execute() and where() methods), and new examples for first(), reset(), and distinct().
- I corrected MigrateClass constraint usage examples in README.md to align with the current implementation.
- I created ROADMAP.md outlining planned features and improvements for SqlDumperClass and MigrateClass.
- I linked ROADMAP.md from README.md.
- I documented a critical syntactic bug in SqlDumperClass's WHERE clause construction in ROADMAP.md and added related warnings in README.md.
diff --git a/README.md b/README.md
@@ -5,7 +5,16 @@
 [![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/furkifor/sql_dumper/Check%20&%20fix%20styling?label=code%20style)](https://github.com/furkifor/sql_dumper/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amaster)
 [![Total Downloads](https://img.shields.io/packagist/dt/furkifor/sql_dumper.svg?style=flat-square)](https://packagist.org/packages/furkifor/sql_dumper)
 
-SQL query builder and database migration tool.
+## About The Project
+
+This package provides tools for database interactions in PHP. It is designed as a project to get SQL query strings in ORM operations, drawing inspiration from Laravel Eloquent's logic. The package offers two main components:
+
+*   **SQL Query Builder**: A fluent interface to construct SQL SELECT queries programmatically.
+*   **Database Migration Tool**: A tool to define and create database table schemas.
+
+## Prerequisites
+
+This package requires PHP 7.2 or higher.
 
 ## Installation
 
@@ -20,92 +29,135 @@ $sql_dumper = new Furkifor\SqlDumper("users");
 
 // Simple query
 echo $sql_dumper->select('*')->get();
-// SELECT * FROM users
+// Output: SELECT * FROM users
 
 // Query with conditions
 echo $sql_dumper->select('name, email')
     ->where('age > ?', [18])
     ->orderBy('name', 'DESC')
     ->limit(10)
     ->get();
-// SELECT name, email FROM users WHERE age > ? ORDER BY name DESC LIMIT 10
+// Output: SELECT name, email FROM users WHERE age > ? ORDER BY name DESC LIMIT 10
 
 // JOIN operations
 echo $sql_dumper->select('users.*, roles.name as role_name')
     ->join('INNER', 'roles', 'users.role_id = roles.id')
     ->where('users.active = ?', [1])
     ->get();
-// SELECT users.*, roles.name as role_name FROM users 
+// Output: SELECT users.*, roles.name as role_name FROM users 
 // INNER JOIN roles ON users.role_id = roles.id WHERE users.active = ?
 
 // Grouping and HAVING
 echo $sql_dumper->select('country, COUNT(*) as user_count')
     ->groupBy('country')
     ->having('user_count > 100')
     ->get();
-// SELECT country, COUNT(*) as user_count FROM users 
+// Output: SELECT country, COUNT(*) as user_count FROM users 
 // GROUP BY country HAVING user_count > 100
+
+// Get the first user
+echo $sql_dumper->select('*')->where('id = ?', [1])->first();
+// Output: SELECT * FROM users WHERE id = ? LIMIT 1
+
+// Select distinct countries
+echo $sql_dumper->select('country')->distinct()->get();
+// Output: SELECT DISTINCT country FROM users
+
+// Resetting the query
+$query = $sql_dumper->select('name')->where('age > ?', [18]);
+echo $query->get(); // Output: SELECT name FROM users WHERE age > ?
+$query->reset();
+// Now the query builder is reset. You can build a new query on $sql_dumper from scratch.
+// For example:
+echo $sql_dumper->select('*')->where('status = ?', ['active'])->get();
+// Output: SELECT * FROM users WHERE status = ?
 ```
 
+### Important Notes on `execute()` and `where()`:
+
+*   **`execute()` Method**: The `SqlDumperClass` includes an `execute()` method. However, this method is a basic implementation that instantiates its own PDO connection internally. This is not suitable for production environments or scenarios requiring configurable database connections. It also directly fetches all results. For more complex applications or production use, it is **highly recommended** to use the `get()` method to retrieve the generated SQL query string and then execute it using your application's existing database connection setup (e.g., your own configured PDO instance or other database abstraction layer).
+
+*   **`where()` Method Safety**: When using the `where()` method, be cautious if you are embedding parameters directly into the condition string, especially for non-numeric values. The safest approach is to use `?` placeholders for values and pass an array of corresponding values as the second argument to `where()`. This helps prevent SQL injection vulnerabilities. For example, `->where('name = ?', ['John Doe'])` is preferred over `->where("name = 'John Doe'")`.
+
 ## Migration Tool Usage
 
+The `MigrateClass` helps you define and create database tables.
+
 ```php
-$table = new MigrateClass("mysql");
+$table = new MigrateClass("mysql"); // Specify the database type (e.g., "mysql", "pgsql")
 
-// Simple table creation
+// Simple table creation with constraints
 $table->name("users")
-    ->string('username', 255)->unique()->notnull()
-    ->string('email', 255)->unique()->notnull()
-    ->string('password', 255)->notnull()
-    ->datetime('created_at')->default("CURRENT_TIMESTAMP")
+    ->string('username', 255, ['UNIQUE', 'NOT NULL'])
+    ->string('email', 255, ['UNIQUE', 'NOT NULL'])
+    ->string('password', 255, ['NOT NULL'])
+    ->datetime('created_at', ['DEFAULT "CURRENT_TIMESTAMP"']) // Note: DEFAULT value needs to be a string within the array
     ->createTable();
 
-// Table with relationships
+// Table with relationships and other constraints
 $table->name("posts")
-    ->string('title', 255)->notnull()
-    ->text('content')
-    ->int('user_id')->notnull()
-    ->foreignKey('user_id', 'users', 'id')
-    ->datetime('published_at')->nullable()
-    ->boolean('is_published')->default(0)
+    ->string('title', 255, ['NOT NULL'])
+    ->text('content') // No specific constraints, column will be TEXT
+    ->int('user_id', ['NOT NULL']) // Assuming user_id is INT and required
+    ->foreignKey('user_id', 'users', 'id') // foreignKey() handles its own specific constraints
+    ->datetime('published_at', ['NULL']) // Explicitly allowing NULL values
+    ->boolean('is_published', ['DEFAULT 0']) // Example for a boolean with a default value
     ->createTable();
 
-// Table with custom constraints
+// Table with custom check constraints
 $table->name("products")
-    ->string('name', 100)->notnull()
-    ->decimal('price', 10, 2)->notnull()
-    ->int('stock')->notnull()->default(0)
-    ->check('price > 0')
-    ->check('stock >= 0')
+    ->string('name', 100, ['NOT NULL'])
+    ->decimal('price', "10, 2", ['NOT NULL']) // Ensure precision and scale are passed as a string if combined
+    ->int('stock', ['NOT NULL', 'DEFAULT 0'])
+    ->check('price > 0') // Table-level CHECK constraint
+    ->check('stock >= 0') // Another table-level CHECK constraint
     ->createTable();
 ```
 
+### Understanding Constraints:
+
+When defining columns using methods like `string()`, `int()`, `datetime()`, etc., you can pass an array of constraint strings as the third argument (or second for `text`, where length is not applicable). Common constraints include:
+
+*   `'NOT NULL'`
+*   `'NULL'`
+*   `'UNIQUE'`
+*   `'PRIMARY KEY'` (though `id()` method is typically used for auto-incrementing primary keys)
+*   `'DEFAULT <value>'` (e.g., `'DEFAULT 0'`, `'DEFAULT "CURRENT_TIMESTAMP"'`, `'DEFAULT "pending"'`)
+*   For data types like `VARCHAR` (string) or `DECIMAL`, the size/precision is usually the second argument.
+
+The `foreignKey()` and `check()` methods apply their specific types of constraints at the table level or column level as appropriate based on their design.
+
 ## Features
 
 ### SQL Query Builder
-- CREATE SELECT queries
-- WHERE conditions
-- JOIN operations (INNER, LEFT, RIGHT)
-- ORDER BY sorting
-- GROUP BY grouping
-- HAVING filtering
-- LIMIT clause
-- Parameter binding support
-- DISTINCT queries
+- Fluent interface to create SELECT queries
+- `WHERE` conditions with parameter binding (using `?`)
+- `JOIN` operations (INNER, LEFT, RIGHT)
+- `ORDER BY` sorting
+- `GROUP BY` grouping
+- `HAVING` filtering
+- `LIMIT` clause for pagination
+- `DISTINCT` queries
+- `first()` method to retrieve a single record (by appending `LIMIT 1`)
+- `reset()` method to clear the current query state
+- `get()` method to retrieve the generated SQL string
 
 ### Migration Tool
-- Multiple database system support (MySQL, MongoDB, SQL Server)
-- Support for all common data types
-- Automatic ID/Primary Key generation
-- Foreign Key relationships
-- Unique constraints
-- NOT NULL constraints
-- DEFAULT values
-- CHECK constraints
+- Support for multiple database systems (e.g., MySQL, SQL Server - driver dependent).
+- Common data types: `string`, `int`, `text`, `datetime`, `boolean`, `decimal`, etc.
+- Automatic `id()` method for auto-incrementing primary keys.
+- Fluent definition for:
+    - Foreign Key relationships (`foreignKey()`)
+    - Column constraints like `UNIQUE`, `NOT NULL`, `DEFAULT` (passed as an array to type methods)
+    - Table-level `CHECK` constraints (`check()`)
+
+## Future Enhancements / Roadmap
+
+We have a documented roadmap for planned features and improvements. You can view it here: [ROADMAP.md](ROADMAP.md)
 
 ## Contributing
 
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please ensure to update tests as appropriate.
 
 ## License
 
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,78 @@
+# Roadmap
+
+This document outlines planned future enhancements and features for the SqlDumper package.
+The project is actively maintained, and contributions are welcome! If you'd like to contribute, please see our [CONTRIBUTING.md](.github/CONTRIBUTING.md) or open an issue to discuss a new feature.
+
+## SqlDumperClass (Query Builder)
+
+The `SqlDumperClass` provides a fluent interface for building SQL SELECT queries. Future enhancements aim to expand its capabilities and improve its robustness:
+
+*   **CRUD Operations:**
+    *   **INSERT Statements:** Add functionality to build `INSERT` queries.
+    *   **UPDATE Statements:** Add functionality to build `UPDATE` queries.
+    *   **DELETE Statements:** Add functionality to build `DELETE` queries.
+
+*   **Enhanced Querying:**
+    *   **Advanced WHERE Clauses:**
+        *   Easier `OR WHERE` conditions.
+        *   Support for nested conditions (e.g., `WHERE (col1 = ? AND col2 = ?) OR col3 = ?`).
+        *   Dedicated methods for `WHERE IN (...)`, `WHERE BETWEEN ...`, `WHERE NULL`, `WHERE NOT NULL`.
+    *   **Subqueries:** Enable the use of subqueries within `SELECT`, `FROM`, or `WHERE` clauses.
+    *   **OFFSET Clause:** Add an `offset()` method for pagination, complementing the existing `limit()` method.
+    *   **Aggregate Function Helpers:** Introduce convenient methods for common aggregate functions with aliases (e.g., `countAs('total')`, `sumAs('amount', 'total_amount')`).
+    *   **Raw SQL Expressions:** Provide a way to inject raw SQL snippets for complex scenarios not covered by the builder.
+
+*   **Execution and Utility:**
+    *   **Improved `execute()` Method:**
+        *   Refactor `execute()` to accept an existing database connection (e.g., PDO, mysqli object) instead of instantiating one internally.
+        *   Allow specifying the fetch mode or returning different types of results (e.g., single row, specific column, success boolean for write operations).
+    *   **Schema Introspection:** Potentially add utility methods to retrieve basic schema information like listing tables or columns (could also be a separate companion utility).
+    *   **Fix WHERE Clause Construction:** Correct the syntactic issue in the `get()` method where `WHERE` clauses are assembled. Currently, it can incorrectly prepend `AND` or `OR` to the first condition (e.g., `SELECT * FROM users WHERE AND age > ?`). The logic needs to ensure that `WHERE` is followed directly by the first condition, and subsequent conditions are correctly appended with `AND` or `OR`.
+    *   **Refined Parameter Handling:** Further review and solidify parameter handling in `where()` clauses to ensure security and prevent SQL injection vulnerabilities, promoting the use of prepared statements for all parameters.
+
+## MigrateClass (Migration Tool)
+
+The `MigrateClass` assists in database table creation. The goal is to evolve this into a more comprehensive migration and schema management tool.
+
+*   **Broader Database Support:**
+    *   **Full Implementation for MongoDB:** Complete the connection and schema generation logic for MongoDB.
+    *   **Full Implementation for SQL Server:** Complete the connection and schema generation logic for SQL Server.
+    *   **Support for PostgreSQL and SQLite:** Extend compatibility to other popular database systems.
+
+*   **Extended Data Types and Constraints:**
+    *   **Additional Data Types:** Introduce support for `DATE`, `TIME`, `TIMESTAMP` (with precision), `FLOAT`, `DOUBLE`, `DECIMAL` (with precision, currently uses `VARCHAR`), `BLOB`, `ENUM`, `SET`, `JSON`.
+    *   **More Column Constraints/Modifiers:**
+        *   `UNSIGNED` for numeric types.
+        *   `ON UPDATE` / `ON DELETE` actions for foreign keys (e.g., `CASCADE`, `SET NULL`).
+        *   Ability to set `PRIMARY KEY` on specific columns or composite keys, not just the default `id`.
+        *   Full support for `INDEX` creation (normal, unique, fulltext).
+        *   `COMMENT` support for tables and columns.
+        *   `CHARACTER SET` and `COLLATION` options per column/table.
+    *   **Fluent Constraint Methods:** Introduce dedicated chainable methods for common constraints like `->unique()`, `->nullable()`, `->default(<value>)` for a more expressive API, aligning with initial README examples.
+
+*   **Schema Manipulation:**
+    *   **Table Alteration (`ALTER TABLE`):**
+        *   Add new columns to existing tables.
+        *   Drop columns from existing tables.
+        *   Modify existing column definitions (type, constraints, default value).
+        *   Rename columns.
+        *   Rename tables.
+        *   Add/drop constraints on existing tables.
+    *   **Dropping Tables:** Implement a `dropTable()` or `dropTableIfExists()` method.
+    *   **Dropping Foreign Keys/Indexes:** Methods to specifically remove these.
+
+*   **Full Migration System:**
+    *   **Migration Tracking:** Implement a system to track executed migrations (e.g., using a dedicated database table).
+    *   **Up and Down Migrations:** Define migrations with `up()` (to apply changes) and `down()` (to revert changes) methods.
+    *   **CLI Tool:** Develop a basic command-line interface (CLI) tool for managing migrations (e.g., `migrate`, `rollback`, `status`).
+    *   **Migration Generation:** Commands to generate new blank migration files.
+
+*   **Data Seeding:**
+    *   Provide a mechanism to define and run seeders for populating tables with initial or test data.
+
+*   **Improved Configuration:**
+    *   Move away from `config.ini` for database connections in `MigrateClass` towards a more flexible configuration approach, perhaps by passing connection parameters or a connection object directly, similar to the proposed changes for `SqlDumperClass::execute()`.
+
+---
+
+This roadmap is subject to change based on community feedback and project priorities.
