From 9f5032f301402bfb7dd58dd686a3301a748ff9c4 Mon Sep 17 00:00:00 2001 From: Lester Caine Date: Sat, 6 Jun 2026 15:12:22 +0100 Subject: BitBase: replace TikiWiki placeholder with architecture docblock Covers the four concerns: DB connection, mInfo/mErrors data hash, APCu object caching, and list utilities (prepGetList/postGetList). Co-Authored-By: Claude Sonnet 4.6 --- includes/classes/BitBase.php | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/includes/classes/BitBase.php b/includes/classes/BitBase.php index 8dbe815..92f1f54 100755 --- a/includes/classes/BitBase.php +++ b/includes/classes/BitBase.php @@ -31,8 +31,40 @@ interface BitCacheable { } /** - * Virtual base class (as much as one can have such things in PHP) for all - * derived bitweaver classes that require database access. + * Abstract root class for all DB-aware bitweaver objects. + * + * Every class that touches the database — content types, user objects, system + * singletons — extends BitBase directly or via LibertyBase / LibertyContent. + * It provides four concerns shared by the entire class hierarchy: + * + * ## Database connection + * + * `$mDb` is set from the global `$gBitDb` on construct and on `__wakeup()`. + * All DB calls go through this reference. `StartTrans()` / `CompleteTrans()` / + * `RollbackTrans()` are thin wrappers that also clear the APCu object cache on + * transaction start (data change implied). + * + * ## Data hash + * + * `$mInfo` is the primary data store for a loaded object — an associative array + * of DB column values populated by `load()` and read via `getField()`. + * `$mErrors` accumulates validation failures from `verify()` and is checked by + * callers via `count($this->mErrors) == 0`. + * + * ## Object caching (APCu) + * + * Optional APCu caching is gated by `isCacheActive()`. Cache keys are scoped + * per host + DB + class + content_id via `getCacheUuidFromKey()`. Subclasses + * opt in by overriding `isCacheableClass()` (returns true) and `getCacheKey()` + * (returns the primary key value). Cache is cleared on `StartTrans()` and on + * `__destruct()` if the object is marked non-cacheable. + * + * ## List utilities + * + * `prepGetList(&$pListHash)` normalises pagination parameters (offset, max_records, + * sort_mode, find) before any `getList()` query. `postGetList(&$pListHash)` builds + * the `listInfo` hash that Smarty pagination helpers consume. Both are static so + * they can be called without a loaded object instance. * * @package kernel */ -- cgit v1.3