Databases

Most WebEngine applications eventually move from static content to persistent state. A to-do list needs somewhere to store items. An address book needs records that survive page refreshes. User accounts need data that belongs to one person and is still there tomorrow.

That is where the database layer becomes part of the normal application path. The lower-level database package is documented in full at https://www.php.gt/docs/Database/Home/.

Connecting to a database

WebEngine reads database settings from configuration and constructs the database service for you. That means page logic and application classes can request the database dependency without having to build the connection manually first.

The main settings live in the [database] section of config.ini, where you choose the driver and connection details. SQLite, MySQL, and other supported drivers all use the same basic approach: WebEngine reads the config, creates the database service, and makes it available through the service container.

Organising SQL and queries

SQL is easier to maintain when it lives outside page logic. Rather than scattering query strings through PHP files, WebEngine projects usually keep them in the query/ directory.

The database package calls these organised sets of queries "query collections". A named query can then be called from PHP by its path-like name rather than by embedding the SQL directly into the page handler.

For example:

query/user/get-by-id.sql

can be called from PHP without the page needing to know the full SQL string. That keeps the PHP focused on the request flow while the SQL remains easy to find and edit in its own file.

The dedicated docs for query collections are here:

• https://www.php.gt/docs/Database/Query-collections/
• https://www.php.gt/docs/Database/Examples/

Using database code from the app

Page logic should normally call an application class or service rather than mixing raw query work everywhere. That way the page handler can stay focused on the request and the response, while the application class can own the data-loading rules and result shaping.

That also gives us a clearer place to decide whether the page should receive:

• raw rows
• a small data object
• a domain entity
• a list already prepared for binding

Using the SQL Builder

As a project grows, some queries may be easier to express as PHP classes rather than plain SQL files. PHP.GT/SqlBuilder exists for that job and is documented at https://www.php.gt/docs/SqlBuilder.wiki/Home/.

Query classes can extend other query classes, which is useful when several related queries share common clauses or conditions. That said, SQL files are still often the clearest starting point. Use the builder when the query genuinely benefits from composition, not simply because it is available.

---

See how everything is loaded on demand in the service container.