PHP Luminova: Abstract Base Class for Model Implementation

The BaseModel serves as the foundation for all models within your application, providing essential functionalities and features to interact with the database in an efficient and secure method.

It allows you to define basic rules for your models, like fields that are allowed to be inserted into the model database table, delete, or update. Additionally, it also supports flagging the model as read-only which limits the model to only perform select statements.

Usage Example

The following example demonstrates how to use the Luminova model to interact with a database table.

Defining the Model

// File: /app/Models/Customers.php

namespace App\Models;

use Luminova\Base\BaseModel;

/**
 * The `Customers` model represents the `customers` table in the database.
 */
class Customers extends BaseModel
{
    /**
     * The table associated with the model.
     */
    protected string $table = 'customers';

    /**
     * The primary key for the table.
     */
    protected string $primaryKey = 'id';
}

Example Usage

Retrieving a Record

use App\Models\Customers;

// Initialize the Customers model
$customers = new Customers();

// Find a person by their ID, retrieving specific columns
$customer = $customers->find(1, ['name', 'email']);

if ($customer) {
    echo "Customer Name: " . $customer->name . "\n";
    echo "Customer Email: " . $customer->email . "\n";
} else {
    echo "No customer found with ID 1.\n";
}

Explanation:

• The find method retrieves a record by its primary key (id in this case) and returns the specified columns (name and email).

Updating or Inserting Records

use App\Models\Customers;

// Initialize the Customers model
$customers = new Customers();

// Check if a record with the given ID exists
if ($customers->exists(1)) {
    // Update the record
    $customers->update(1, [
        'name' => 'Peter',
        'email' => '[email protected]',
    ]);
    echo "Record updated successfully.\n";
} else {
    // Insert a new record
    $customers->insert([
        [
            'name' => 'Peter',
            'email' => '[email protected]',
        ]
    ]);
    echo "New record inserted successfully.\n";
}

Class Definition

• Class namespace: \Luminova\Base\BaseModel
• This class is an Abstract class
• This class implements: \Luminova\Interface\LazyInterface

Properties

table

Model table name name.

protected string $table = '';

primaryKey

The default primary key column name for table, this will be used while selecting, updating and more.

protected string $primaryKey = '';

searchable

Define your database table searchable columns, the fields that search will have to look for queries.

protected array<int,string> $searchable = []

cacheable

Enable or disable database caching for model while calling select, find, search, total or count.

protected bool $cacheable = true;

expiry

Database cache expiration time TTL in seconds.

protected DateTimeInterface|int $expiry = 7 * 24 * 60 * 60;

readOnly

Specify whether the model's table is updatable, deletable, and insertable.

protected bool $readOnly = false

insertable

Define fields that can be inserted into.

protected array $insertable = []

updatable

Define fields that can be updated.

protected array $updatable = []

rules

Define your Input validation rules based on Validator class rules.

protected array<string,string> $rules = []

messages

Define your Input validation rules errors messages.

protected array<string,array> $messages = []

builder

Database query builder class instance.

protected ?Luminova\Database\Builder $builder = null;

validation

Input validation class instance.

protected static ?Luminova\Security\Validation $validation = null;

Methods

constructor

Initialize the constructor for the Model class.

public __construct(): mixed

insert

Insert a new record into the current database.

public insert(array<string,mixed> $values): bool

Parameters:

Return Value:

bool - Return true if records was inserted, otherwise false.

Throw Exception:

\Luminova\Exceptions\RuntimeException - Throws if insert columns contains column names that isn't defined in $insertable.

update

Update current record in the database.

public update(array<int,mixed>|string|float|int|null $key, array $data, ?int $max = null): bool

Parameters:

Return Value:

bool - Return true if records was updated, otherwise false.

Throw Exception:

\Luminova\Exceptions\RuntimeException - Throws if update columns contains column names that isn't defined in $updatable.

find

Fine next or a single record from the database table.

public find(array<int,mixed>|string|float|int $key, array<int,string> $fields = ['*']): mixed

Parameters:

Return Value:

mixed - Returns selected records or false on failure.

select

Select records from the database table.

public select(
    string|int|float|array<int,mixed>|null $key = null, 
    array<int,string> $fields = ['*'], 
    int $limit = 100, 
    int $offset = 0
): mixed

Parameters:

Return Value:

mixed - Returns selected records or false on failure.

search

Select records from the database.

public search(string $query, array<int,string> $fields = ['*'], int $limit = 100, int $offset = 0): mixed

Parameters:

Return Value:

mixed - Returns found records or false on failure.

delete

Delete a record from the database.

public delete(string|array<int,mixed>|float|int|null $key = null, int $max = 1): bool

Parameters:

Return Value:

bool - Return true if the record was successfully deleted otherwise false.

total

Get total number of records in the database.

public total(): int|bool 

Return Value:

int|bool - Return the number of records or false if failed.

count

Get total number of records in the database based on the keys.

public count(array<int,mixed>|string|float|int $key): int|bool 

Parameters:

Return Value:

int|bool - Return the number of records or false if failed.

exists

Determine if a record exists in the database.

public exists(string|int|float $key): bool 

Parameters:

Return Value:

bool - Return true if the record exists otherwise false.

purge

Deletes all cache entries related to the current model.

This method removes all cache files for the model from the cache directory. The path is constructed based on the model's class name and is expected to be within the filesystem cache directory.

public purge(): bool

Return Value:

bool - Returns true if the cache files are successfully deleted, false otherwise.

validation

Initialize and ser validation class object.

protected validation(): Luminova\Security\Validation

Return Value:

Luminova\Security\Validation - Return the number of records.

After first initialization you can then use static::$validation to access the object.

doSearch

Run a search in database table using the $searchable to index search columns. This method uses third-party libraries to search database table.

public doSearch(
    string $query, 
    array $fields = ['*'], 
    int $limit = 100, 
    int $offset = 0, 
    string $flag = 'any'
): mixed

Parameters:

Return Value:

mixed - Return found records or false on failure.

Throws:

• \Luminova\Exceptions\RuntimeException - If search controller class is not installed.

To use this method or searchInstance you will first have to install a third party library by running composer command composer require peterujah/php-search-controller .

searchInstance

Return search controller class instance.

protected searchInstance(string $flag): \Peterujah\NanoBlock\SearchInstance

Parameters:

Return Value:

SearchInstance - Search controller instance.

Throws:

• \Luminova\Exceptions\RuntimeException - If the search controller class is not installed.

Search Flags

The $flags keys to predefined search behaviors in the SearchInstance class. Here are the available flags and their corresponding behaviors:

• 'start': Matches records that start with the query string.
• 'end': Matches records that end with the query string.
• 'any': Matches records that contain the query string anywhere within the field.
• 'second': Matches records that contain the query string in the second position (specific use case).
• 'length2': Matches records that start with a query string of length 2.
• 'length3': Matches records that start with a query string of length 3.
• 'startend': Matches records that start and end with the query string.

getTable

Get the name of the database table associated with this model.

public getTable(): string

Return Value:

string - Return the name of the database table.

getKey

Get the primary key field name for this model.

public getKey(): string

Return Value:

string - Return the primary key field name.

getSearchable

Get the table searchable array of column names.

public getSearchable(): array<int,string>

Return Value:

array<int, string> - Return table searchable column names.

getConn

Get instance of database connection.

public getConn(): Luminova\Interface\DatabaseInterface

Return Value:

DatabaseInterface - Return database driver connection instance.

Throws:

• \Luminova\Exceptions\DatabaseException - Throws if database connection failed.

getBuilder

Get instance of database builder class.

public getBuilder(): ?Luminova\Database\Builder

Return Value:

Builder|null - Return the instance database builder.

getLastInsertedId

Retrieve last inserted id from database after insert method is called.

public getLastInsertedId(): mixed

Return Value:

mixed - Return last inserted id from database.

setReturn

Change the database result return type (e.g, array or object).

public setReturn(string $returns): self

Parameters:

Return Value:

self - Return instance of model class.

isReadOnly

Check if method is read only

public isReadOnly(): bool

Return Value:

bool - Return true if is read only otherwise false.