Entities

DatabaseFactory uses the entity system to model and modify data. An entity is an object representation of a database table within the database you're working with. When working with entities, we are using these objects to model, store, or modify table information based on that objects properties. It's important to note that in order to use the Query Builder, entities are not required.

Create a new entity

// this class must extend the base entity class
class User extends DatabaseFactory\Entity 
{
    // all fields you want to work with are properties 
    // within this class
    public string $name; 
    public string $email; 
}

Table Assignment

When using entities (EG: while using the ORM), there is a background process that runs which attempts to intelligently guess the name of the table that we're working with. For example (and on all subsequent examples) we are working with the User entity class. The internal entity system will assume that any entity objects created from this class belong to the users table and DatabaseFactory will attempt to work on that table, if it exists.

If you'd like to work on a different table than the auto-detected one, and essentially treat the entity as more of a model, you can simply assign the $table property within your entity class.

class User extends DatabaseFactory\Entity 
{
    // to use a different table than the auto-detected
    // one, we assign $table a new value here
    protected string $table = 'custom_table';

    // ...
}

ORM Modules

The entity class that we've built also has special access to certain ORM modules. These modules are used in the form of trait's and can be imported into your entity to allow for different ORM features to be enabled only when needed, on a per-entity basis. An example of how to implement these features is shown below.

Let's say we want to give our entity class access to the find() and all() methods. What we need to do is import the ORM modules, and we can use them within our code.

use DatabaseFactory\ORM;

class User extends DatabaseFactory\Entity 
{
    use ORM\HasFind;
    use ORM\HasAll;
}

Now, when we call our entity class, we'll have access to the find() and all() methods, like so:

# generate the query using find()
$user = User::find(10) // retrieves the user record with the ID of 10

# generate the query using all()
$users = User::all() // retrieves all user records

The available ORM modules are as follows, with more to come. - [view src]:

Module	Function
DatabaseFactory\HasFind	Returns a single record based on the provided parameters
DatabaseFactory\HasAll	Returns all records associated with the database table
DatabaseFactory\HasFirst	Returns the first record in the database results
DatabaseFactory\HasLast	Returns the last record in the database
DatabaseFactory\HasLike	Generates a WHERE LIKE query
DatabaseFactory\HasNot	Generates a WHERE NOT query
DatabaseFactory\HasTransact	Generates a transaction
DatabaseFactory\HasWhere	Generates a WHERE query
DatabaseFactory\HasUpsert	Add new, or modify existng data
DatabaseFactory\HasJoin	Generates a JOIN query

Now that we have an entity class, we can modify our data, and use the entity to retrieve data while using the ORM.