Initiall commit

README.md

@@ -1,2 +1,216 @@
-# turborfq
+# MariaDB Excel-like Web UI
 
+A lightweight PHP web application that provides an Excel-like interface for browsing and editing MariaDB tables.  
+Users authenticate with **their own MariaDB credentials**, and the app works with *any* schema by reading metadata from `information_schema`.
+
+> Note: This README assumes a Linux environment with PHP 8.1+ and MariaDB available.
+
+---
+
+## Features
+
+- Login with native MariaDB user/password (no separate app users).
+- Side menu with database → table tree.
+- Central Excel-like grid built dynamically from table metadata.
+- Column header filters (per-column search).
+- Server-side pagination.
+- Basic CRUD operations:
+  - Insert new rows.
+  - Edit existing rows.
+  - Delete rows.
+- Generic, schema-agnostic behavior using `information_schema`.
+
+---
+
+## Tech Stack
+
+- **Backend**
+  - PHP 8.1+
+  - Slim 4 (microframework for routing and middleware)
+  - PHP-DI (dependency injection)
+  - PDO (MariaDB/MySQL driver)
+
+- **Frontend**
+  - Vanilla JS
+  - [Tabulator](https://tabulator.info/) for interactive data grid (filters, pagination, editing)
+
+---
+
+## Project Structure
+
+```text
+project/
+  composer.json        # Project metadata and PHP dependencies
+  vendor/              # Installed Composer packages (generated)
+  public/
+    index.php          # Front controller, routes, serves index.html
+    index.html         # Basic layout (sidebar + toolbar + grid)
+    app.js             # Frontend logic (Tabulator + API calls)
+  src/
+    Db.php             # PDO factory based on session credentials
+    MetaService.php    # Schema/metadata from information_schema
+    DataService.php    # Generic SELECT/INSERT/UPDATE/DELETE
+```
+
+---
+
+## Prerequisites
+
+- PHP 8.1+ with:
+  - `pdo_mysql` extension enabled
+  - `mbstring`, `xml` (typical for Composer and frameworks)
+- Composer (global installation recommended)
+- Access to a MariaDB server
+
+Example (Debian/Ubuntu):
+
+```bash
+sudo apt update
+sudo apt install php php-cli php-mbstring php-xml php-mysql unzip git
+```
+
+Install Composer globally (simplified example):
+
+```bash
+php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
+php composer-setup.php --install-dir=/usr/local/bin --filename=composer
+php -r "unlink('composer-setup.php');"
+```
+
+---
+
+## Installation
+
+1. Clone or copy the project:
+
+```bash
+cd /path/to
+git clone <your-repo-url> mariadb-grid
+cd mariadb-grid
+```
+
+2. Install PHP dependencies:
+
+```bash
+composer install
+```
+
+This reads `composer.json` and installs Slim, PHP-DI and all required packages into `vendor/`.
+
+---
+
+## Configuration
+
+By default, `Db.php` uses:
+
+- Host: `localhost`
+- Port: `3306`
+- Charset: `utf8mb4`
+
+If your MariaDB server is different, update the DSN in `src/Db.php`:
+
+```php
+$dsn = 'mysql:host=localhost;port=3306;charset=utf8mb4';
+```
+
+No database name is hardcoded: the app reads available schemas from `information_schema` and shows only those the connected user can see.
+
+---
+
+## Running the App (Development)
+
+Use PHP’s built-in web server and point it to the `public` directory:
+
+```bash
+cd /path/to/mariadb-grid
+php -S localhost:8080 -t public
+```
+
+Open in your browser:
+
+```
+http://localhost:8080/
+```
+
+> The built-in server is intended for development/testing only. For production use, configure a real web server (Nginx/Apache) with `public/` as document root and `index.php` as front controller.
+
+---
+
+## Usage
+
+1. Open the app in a browser.
+2. In the top login panel:
+   - Enter MariaDB username.
+   - Enter MariaDB password.
+   - Click **“Login”**.
+3. If the connection succeeds:
+   - The left sidebar will show databases and tables as a tree.
+4. Click any table:
+   - The central Tabulator grid will load the table’s data.
+   - Column header filters allow you to filter per column.
+   - Pagination is handled server-side.
+
+### CRUD operations
+
+- **Insert**
+  - Click **“Insert”**.
+  - A new row is created (you can extend logic to open an editor or use default values).
+- **Update**
+  - Select a row (click to highlight it).
+  - Edit cells directly in the grid.
+  - Click **“Save row”** (or whatever label you use) to send the updated row to the backend.
+- **Delete**
+  - Select one or more rows.
+  - Click **“Delete”**.
+  - Confirm the deletion.
+
+> Updates and deletes are performed using the table’s primary key.  
+> If there is no primary key, it is safer to treat the table as read-only.
+
+---
+
+## How It Works (High Level)
+
+- On login, the app tests a connection to MariaDB using the supplied credentials and stores them in the session.
+- For all subsequent API requests, PDO is created with these credentials, so MariaDB’s own permissions control what the user can see and edit.
+- `MetaService` queries `information_schema` to:
+  - Build the schema → tables tree.
+  - Load column definitions and detect the primary key.
+- `DataService` builds generic, parameterized SQL statements for:
+  - Paginated `SELECT` (with simple `LIKE` filters per column).
+  - `INSERT` (skipping `auto_increment` columns).
+  - `UPDATE` / `DELETE` by primary key.
+- The frontend (Tabulator) requests data and metadata via JSON and renders an editable grid.
+
+---
+
+## Customization Ideas
+
+- Map column `DATA_TYPE` to more specific editors (date picker, number editor, dropdowns).
+- Add sorting synchronization (Tabulator sorters → backend `ORDER BY`).
+- Add bulk insert/update operations using transactions.
+- Add read-only mode for tables without primary keys.
+- Add simple configuration file for allowed schemas, default page size, etc.
+
+---
+
+## Troubleshooting
+
+- **Blank page or PHP errors**  
+  Make sure `display_errors` is enabled in development, or check web server error logs.
+
+- **“Not authenticated” / 401 responses**  
+  Ensure you logged in successfully and that your browser accepts cookies (session).
+
+- **Cannot connect to MariaDB**  
+  - Verify host/port in `Db.php`.
+  - Confirm credentials using `mysql` client or another tool.
+  - Check firewall and bind-address on the MariaDB server.
+
+---
+
+## License
+
+This project is intended as a starting point/template.  
+Use and adapt it freely within your environment and licensing requirements of the included libraries (e.g., Tabulator, Slim, etc.).
+```