Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Databases & Cortex

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 Model class 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 IDENTITY rather than a serial column, 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-written and 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.