Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
239 lines (182 loc) · 10 KB

ARCHITECTURE.md

File metadata and controls

239 lines (182 loc) · 10 KB
Raw

Project Architecture Summary

1) Overview

DHTMLSQL is a zero-setup, lightweight PHP library that wraps PHP's mysqli extension with a safer, more ergonomic API. Its primary deliverable is a single class file. The repository also ships a shared connection bootstrap and a set of standalone demo scripts that serve as living documentation.

  • Core library: library/dhtmlsql.php
  • Shared DB bootstrap: config.default.php
  • Demo index page: examples/index.php
  • Demo scripts: examples/source/*.php
  • Smoke-test harness: test.php
  • Package manifest: composer.json

This is not an MVC web application. There is no framework, no router, no template engine, and no asset pipeline. The architecture is best understood as a library + demo site.

2) Directory Structure

dhtmlsql/
├── library/
│   └── dhtmlsql.php          # Single-file library (the DHTMLSQL class)
├── examples/
│   ├── index.php             # HTML navigation page linking to each demo
│   ├── dbtest.sql            # MySQL fixture for demo setup
│   └── source/               # Executable demo scripts
│       ├── connect[1-6].php  # Connection style examples
│       ├── select.php
│       ├── insert.php
│       ├── insert_bulk.php
│       ├── insert_ignore.php
│       ├── insert_duplicate.php
│       ├── query[1-4].php
│       ├── createtable.php
│       ├── import.php
│       ├── export.php
│       ├── pager1.php
│       ├── pager2.php
│       └── sample.sql        # SQL fixture used by import/export demos
├── config.default.php        # Shared DB connection bootstrap
├── test.php                  # Minimal smoke test
├── composer.json             # Composer package definition
├── LICENCE
└── README.md

3) Routing

There is no framework router or front controller.

The web server maps URLs directly to PHP files on disk (file-based routing):

URL File
/examples/index.php Demo landing page
/examples/source/select.php SELECT demo
/examples/source/insert.php INSERT demo
/examples/source/pager1.php Pagination demo
/examples/source/import.php Import demo
/examples/source/export.php Export demo
... ...

Each PHP file runs immediately on request.

4) Controllers (or Equivalent)

There are no controller classes. Each script under examples/source/ acts as its own self-contained controller:

Connection demos (connect1.php – connect6.php)

  • Demonstrate different instantiation styles: new DHTMLSQL(), DHTMLSQL::connect(), DHTMLSQL::get()->connect(), connection reuse, and persistent connections.
  • Each independently requires library/dhtmlsql.php and verifies $db->connected().

CRUD demos (select.php, insert.php, insert_bulk.php, insert_ignore.php, insert_duplicate.php, query1–4.php, createtable.php)

  • All require ../../config.default.php for a ready $db handle.
  • Call shorthand methods (select, insert, insert_bulk, insert_update, update, del, query) and dump results.

Import/export demos (import.php, export.php)

  • import.php calls $db->import("sample.sql") to replay SQL statements from a file.
  • export.php calls $db->export('*', 'sample.sql') to dump the database to a file.

Pagination demos (pager1.php, pager2.php)

  • Call $db->pquery($sql, $items_per_page, $url_param) which automatically slices results using a $_GET variable and exposes navigation HTML via $db->show_navigation().

Each script follows the same three-step pattern:

  1. Include shared config (../../config.default.php).
  2. Call one or more DHTMLSQL methods on $db.
  3. Print output directly (echo, var_dump, or header-triggered download).

5) The DHTMLSQL Class (Library Core)

All business/data-access logic lives in library/dhtmlsql.php. It is a singleton-capable, chainable class.

Instantiation

Style Code
Static factory $db = DHTMLSQL::connect($host, $user, $pass, $db)
Static singleton $db = DHTMLSQL::get()
Procedural $db = new DHTMLSQL(); $db->connect(...)
Reuse existing mysqli DHTMLSQL::connect($existingMysqliObject)

Public API surface

Connection

  • connect() / _connect() — open connection; accepts host, user, password, dbname, port, socket, or an existing mysqli object
  • connected() — returns boolean
  • connect_error() — returns error string
  • set_charset($charset, $collation) — sets NAMES and collation on the connection

Queries

  • query($sql, $replacements) — raw query with ? placeholder auto-escaping; supports scalar and array replacements (for IN (?))
  • select($columns, $table, $where, $replacements, $order, $limit) — shorthand SELECT
  • dlookup($column, $table, $where, $replacements) — fetch a single value or row
  • insert($table, $columns, $ignore) — shorthand INSERT; when $ignore is an array, delegates to insert_update
  • insert_bulk($table, $columns, $data, $ignore) — multi-row INSERT in a single query
  • insert_update($table, $columns, $update) — INSERT … ON DUPLICATE KEY UPDATE; supports the INC(n) / INC(-n) increment shorthand
  • replace($table, $columns) — shorthand REPLACE INTO
  • update($table, $columns, $where, $replacements) — shorthand UPDATE; supports INC(n) increment shorthand
  • del($table, $where, $replacements) — shorthand DELETE

Fetch

  • fetch_assoc() — fetch one row as associative array (falls through to mysqli_result via __call)
  • fetch_assoc_all() — fetch all rows as an array of associative arrays
  • fetch_array() — fetch one row as numeric array (via __call fallback)
  • fetch_row() — fetch one row (via __call fallback)
  • reset_result() — rewind internal result pointer

Result metadata

  • num_rows() / $db->num_rows — row count from last query
  • affected_rows() — rows affected by last INSERT/UPDATE/DELETE
  • insert_id() — auto-increment ID from last INSERT
  • fetch_sql() — returns the last executed SQL string

Utilities

  • escape($string) — mysqli_real_escape_string wrapper
  • implode($pieces) — escape-aware comma-join for IN clauses
  • table_exists($table) — SHOW TABLES check
  • truncate($table) — TRUNCATE shorthand
  • optimize() — OPTIMIZE TABLE for all tables with overhead
  • db_prefix_tables($stmt, $prefix) — replace {tablename} tokens with a prefix
  • get_table_status() — SHOW TABLE STATUS wrapper

Import / Export

  • import($path) — parse and execute a .sql file line by line
  • export($tables, $file) — dump table structure + data to a file or trigger a browser download
  • fetch_table($table) — generate the SQL dump string for a single table

Pagination

  • pquery($sql, $items_per_page, $pager_variable) — auto-paginating query; reads $_GET[$pager_variable] for current page and slices results with LIMIT
  • show_navigation() — renders HTML pagination links

Developer ergonomics

  • preview($mode) — when true, prints SQL to screen instead of executing (useful in development)
  • session_logging / session_logger — log all executed SQL to a file
  • reset_session_logger() — clear the log file
  • halt_on_error / print_error — control error behavior
  • halt($message) — error handler; delegates to a global halt() function if one exists
  • __call($name, $args) — transparent fallback to mysqli connection or mysqli_result methods (enables raw prepared-statement usage)
  • __get($name) — transparent property proxy to result or connection objects (e.g., $db->host_info, $db->insert_id)

6) Shared Bootstrap (config.default.php)

Used by the majority of example scripts via require "../../config.default.php". It:

  1. Requires library/dhtmlsql.php.
  2. Connects to the local dbtest database (localhost / admin / pass).
  3. Calls $db->set_charset('utf8', 'utf8_general_ci').
  4. Leaves a $db variable in scope for the including script.

7) Views

There is no template engine or reusable view layer.

  • examples/index.php is a plain HTML page with a minimal inline <style> block. It acts as a navigation hub linking to each demo script.
  • Demo scripts in examples/source/ render output directly using echo and var_dump, or send raw HTTP download headers (Content-Disposition: attachment).

8) Assets Structure

There is no dedicated assets folder, build pipeline, or front-end tooling.

  • The only styling is a small inline <style> block in examples/index.php (sets text-decoration on anchor tags).
  • No JavaScript, images, fonts, or CSS files exist in this repository.

9) Runtime Flow

Typical lifecycle for a demo endpoint:

HTTP request
  └─► examples/source/<script>.php
        └─► require ../../config.default.php
              └─► require library/dhtmlsql.php   (loads DHTMLSQL class)
              └─► DHTMLSQL::connect(...)          (opens mysqli connection)
              └─► $db->set_charset(...)
        └─► $db->query() / select() / insert() / pquery() / import() / export()
              └─► mysqli::query() (internal)
              └─► session_log() (if enabled)
        └─► echo / var_dump / header() + echo     (response)

10) Packaging and Dependencies

Concern Detail
Composer type library
PHP requirement >= 5.1.0
PHP extension mysqli
Autoload strategy autoload.files — includes library/dhtmlsql.php on every request
Zero-setup usage Drop-in: require 'dhtmlsql.php'
Packagist slug dhtml/dhtmlsql

11) Practical MVC Mapping

MVC layer This project's equivalent
Model / data-access library/dhtmlsql.php (DHTMLSQL class)
Controller Procedural scripts in examples/source/
View examples/index.php (HTML nav) + direct echo in scripts
Assets None (inline CSS only)
Router Web server file mapping (no framework router)