phpengine/specs/integrations/mysql.md

Read this when changing MySQL connections, mappers, transactions, or persistence invariants.

MySQL Persistence

Implementing Files

File	Key symbols
src/Core/System/System.php	F3 DB\SQL connection and PDO options
src/Core/System/User.php	users mapper, role serialization, password hash generation
src/Core/System/Notifications.php	notifications mapper and table-wide clear operation
src/Core/Api/UserController.php	Account CRUD, row locks, transactions, duplicate detection
phengine.sql	Schema, unique index, and sample data

Flow

1. F3 globals provide DSN and database credentials to System.
2. System creates the DB\SQL connection with PDO exceptions and stores it as F3 DB.
3. Mappers obtain the global connection and issue F3 mapper operations.
4. User updates/deletes begin a transaction, lock user rows, enforce account invariants, then commit or roll back.

Trust Boundaries

Boundary	Mechanism	Location
Connection secrets	Values originate in runtime configuration, not request input	cfg/config.bin loaded by index.php
Request values in queries	Mapper predicates use placeholders for username/ID lookups	User, AuthController, UserController
Duplicate identities	Application precheck plus uq_users_username database constraint	UserController, phengine.sql
Final administrator race	Transaction and SELECT id FROM users FOR UPDATE serialize checks and mutations	UserController
Role deserialization	unserialize(..., ['allowed_classes' => false]) prevents object instantiation	User::__construct()
Table-wide notification deletion	Only authenticated, CSRF-protected notification API path reaches emptyAll()	NotificationController::delete()

Config

• Driver: MySQL DSN from F3 DSN global.
• PDO: ERRMODE_EXCEPTION is set; persistence is enabled on Linux or CLI.
• F3 query logging: disabled with $db->log(false) to avoid known framework memory leakage.

See database conventions and identity spec.