1. INTRODUCTION

An entity is a PHP object for one database record. Set its properties, then call save() to store them.

Entities belong in App/Backend/Database/ and extend Backend\Core\Entity. We’ll use the articles table from the Database guide.

2. CREATING AN ENTITY

Create App/Backend/Database/Article.php:

<?php declare(strict_types=1);

namespace Backend\Database;

defined("ACCESS") or exit("Access Denied");

use Backend\Core\Entity;

class Article extends Entity
{
    protected string $table = "articles";
    protected string $primary_key = "id";

    protected array $columns = [
        "id" => "int unsigned NOT NULL AUTO_INCREMENT",
        "title" => "varchar(200) NOT NULL",
        "published" => "tinyint(1) NOT NULL DEFAULT 0",
        "created_at" => "datetime NULL",
    ];

    public ?int $id = null;
    public string $title = "";
    public int $published = 0;
    public ?string $created_at = null;
}

Define the table and columns, then add a public property for each column. Keep the column definitions the same as those in Articles.php.

The property defaults give a new article its starting values. Use types that match the database columns, including nullable types for columns that accept null.

3. CREATING A RECORD

Add the Article import near the top of your PHP file, then create and save a record:

use Backend\Database\Article;

$article = new Article();
$article->title = "My First Article";
$article->published = 0;
$article->created_at = date("Y-m-d H:i:s");

if ($article->save())
{
    echo "Record saved.";
}

The first save() inserts the article. Further saves on that object update the same record. The framework creates the table if it is missing.

Set the values you want before saving. save() writes every column except the primary key, including properties set to null. This example lets MySQL generate the ID.

4. LOADING AND UPDATING

To load a record, pass its ID when creating the object. Using the Article import above:

$article = new Article(42);

if ($article->id === null)
{
    echo "Article not found.";
}
else
{
    $article->title = "Updated Article";
    $article->published = 1;
    $article->save();
}

Check that the record was found before updating it. If loading found nothing, save() would create a new record instead.

To use another configured database connection:

$article = new Article(42, "secondary");

For a new record on that connection, use new Article(null, “secondary”).

Check property values before saving. All column values are written each time, and changing the public id property does not change which record gets updated.

5. DELETING A RECORD

Load the record, check that it exists, then call delete():

$article = new Article(42);

if ($article->id !== null)
{
    $article->delete();
}

Deleting clears the entity’s saved-record state but leaves its property values in place. Saving that object again would insert a new record. If the object has no saved record, delete() returns false.

6. WORKING WITH DATABASE CLASSES

Use Articles when you need a list or a filtered query:

use Backend\Database\Articles;

$articles = new Articles();
$rows = $articles->table()->where("published", 1)->get();

Use Article when you want to load and save one record through its properties.

The rows returned by Articles are ordinary objects. To edit one as an entity, load it with new Article($id), then change its properties and save it.