Models - aPisC/phroper GitHub Wiki

Models are used to describe the database structure and to handle database queries. Models are inherited from Phroper/Model class and the defined models has to be in the Models namespace. Models can be edited through REST api if the default service mode is allowed.

Creating a model

To build a model in the constructor you have to specify the fields of an entity. There are builtin field types you can use, or you can implement new field types based on existing classes.

Initial fields

All models are initialized with 4 fields:

  • id: auto incremented primary key, to identify the entities
  • created_at: timestamp to store the creation time of an entity
  • updated_at: timestamp that automatically uptades to current time on updating an entity
  • updated_by: id of the user that updated the entity These fields can de deleted from model by setting them to null in constructor.

Example of model

This code will initialize a model with 2 fields, on top of the default ones, the first is a foreign key references the id field of the AuthRole model, the second field is a Text field.

class AuthPermission extends Model {
  public function __construct() {
    parent::__construct(["sql_table" => 'permission']);
    $this->fields["role"] = new RelationToOne("AuthRole", ["required", "sql_delete_action" => "CASCADE"]);
    $this->fields["permission"] = new Text();
  }
}

Models can be described as Json files. These files are located in the Models folder of the project, contains a json object, all members in the root object will be passed to model configuration array, except the fields object, it is used to describe the fields of the model. A field can be an array where the first parameter is the type of the field, and all the remaining parameter is passed to field constructor. If a string is provided instead of an array it will be interpreted as an array with one member. If you want to remove predefined fields, set them to null in json.

Equivalent example of AuthPermission model:

{
  "sql_table": "permission",
  "fields": {
    "role": ["RelationToOne", {"required": true, "sql_delete_action": "CASCADE"}],
    "permission": "Text"
  }
}

Using models

Models has predefined functions to handle sql queries automatically.

findOne($filter, $populate=null)

Will return one entity by the given filter object, and will automatically populate the fields given in the populate parameter. If no populate parameter provided, it will use the populate setting from model data, or will generate a population list by the default settings of fields. If no entity found, it will return null instead.

find($filter, $populate=null)

This function will return a list of entities that meets the given filter. The maximum number of entities is limited, but you can specify the limit and start properties of the SQL select in the filter. The relation populating is working the same as in the findOne function.

count($filter)

Returns the number of entities that meets the given filter.

create($entity)

This function will insert the given entity to the database, and return the new data.

createMulti($entities, $processEntities=true)

This function will insert a list of entities in the same query to the table and returns a list of new entities. If the second parameter is false, there will be no lifecycle updates on the fields and won't return the new entities. This mode can be used if the data after insertion is not necessary.

update($filter, $entity)

This function will update all records in the table that meets the given filter with the data given in the $entity parameter. It will return the updated entities, null if no value updated, the updated entity if there was exactly one update, and a list if updated multiple entiuties.

delete($filter)

It will delete all entities from the table that meets the given filter, and will return the modified values just like the update function.

init()

This function will create the sql table of the model andf creates all other tables thar are referenced in fields. Returns true if the model needed initialization. If you want to insert records to databas initially, use the parent's init function in a condition, and insert the required values accordingly.

Initialization of the role model:

  public function init() {
    if (parent::init()) {
      $this->create([
        "name" => "default",
        "isDefault" => true,
      ]);

      return true;
    }
    return false;
  }

Configuring models

Model accepts configuration values in its constructor as an associated array. All values that not starting with sql_ will be sent to the user interface. Available setting values:

Parameter name Description Default
display This field will be displayed on ui to identify the entity id
primary Primary key of the model id
visible Determinates if the model is displayed on the admin panel true
editable Determinates if the data can be edited through admin panel true
key Identifier of the model, it will be accessed through this key auto generated id
name Name of the model, will be displayed on admin panel Key as readable text
sql_table Model will use this sql table in the background Key of the model
default_service If true, the model will be editable through default Rest apis true