Databases & Cortex
- Database Configuration
- Cortex ORM
- Database Migrations
- Model Class
- Reading a Record Back After an Insert
- Uniqueness Checks
- Query Return Type
Database Configuration
For configuring database access, the framework follows the guidelines outlined by the Fat-Free Framework. This includes setting up database connections and handling queries efficiently.
Cortex ORM
The framework utilizes Cortex ORM for object-relational mapping, simplifying interactions with the database. For detailed usage and configuration instructions, refer to the Cortex documentation.
Database Migrations
Database migrations are managed using the Phinx library, which is included in the template application with
a phinx.json file. This file can be customised, although Phinx is the recommended tool. Comprehensive documentation
for Phinx is available here.
Model Class
The Model class provides a structured way to access data using Cortex ORM. It includes methods for pagination, data
conversion, and change detection, ensuring robust and efficient data handling.
Note
Sukarix Convention: Model timestamps
The
Modelclass follows conventions for managing timestamps:
- created_on: Automatically set when a record is created.
- updated_on: Automatically updated when a record is modified.
Reading a Record Back After an Insert
Model::insert() reads the record back when the insert left it blank, so the values the
database assigned — the identifier, the defaults, the timestamps — are in memory when
save() returns.
This is not cosmetic. PostgreSQL identity columns carry no nextval default, so Fat-Free
does not recognise them as auto increment. The reload Cortex runs itself then filters on
the identifier the record held before the insert, matches nothing, and leaves the whole
record blank. Without the read-back, every model is empty immediately after being saved.
Note
Sukarix Convention: Identity columns
A schema created for PostgreSQL 10 or later normally uses
GENERATED BY DEFAULT AS IDENTITYrather than aserialcolumn, and is therefore affected. No application code is required —Model::insert()handles it.
Uniqueness Checks
Model::excludeId() adds an identifier exclusion to a filter, and drops the clause when
there is no identifier to exclude:
// While creating a record, $id is null and the filter is left alone.
$taken = $this->load($this->excludeId(['lower(name) = ?', $name], $id));
Writing the clause by hand is a common and silent mistake:
// Wrong: matches nothing while creating a record.
$this->load(['lower(name) = ? and id != ?', $name, $id]);
Comparing against a null identifier yields NULL in SQL, not true, and NULL makes the
whole condition unsatisfiable. The uniqueness check then passes for every record, and
duplicates are accepted.
Caution
Uniqueness checks and null identifiers
Always build the exclusion with
excludeId(). A hand-writtenand id != ?disables the check it is part of whenever the identifier is null.
Query Return Type
Cortex documents find() as returning an array of records; it returns a
DB\CortexCollection. Model::find() declares the real type, so castAll() and the other
collection methods resolve for static analysis and in an editor.