4. Models

This framework is agnostic and does not engage in creating databases and database tables. The database for your application should be created using the language of your choice. This framework uses a PDO adapter to interface with your database tables. We recommend using MySQL given its tight integration with PHP but other databases can be used at your own discretion.

CRUD operations on a database

In this video, we will learn how to create a database model, how to link it to Caligrafy and how to perform CRUD operations using Controllers.

Activating Databases

In order to start using the database, you need to activate it. The .env file is where the database credentials need to be entered. Note that the DB_ACTIVATE variable in the .env file needs to be set to true to activate the connection.

DB_ACTIVATE=true
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your-db-name
DB_USERNAME=your-db-username
DB_PASSWORD=your-db-password

Relational Databases

Creating databases and database tables is achieved through the database language that you normally use. This framework does not dictate how your database should be created. The examples in this documentation are all using MySQL. MySQL is the SQL language that we recommend using.

• Your database needs to be created with all its tables before creating the Models in this framework:

/* Example of a MySQL script without relationships */

CREATE TABLE `books` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(255) NOT NULL,
  `author` varchar(255) NOT NULL,
  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8;

• The One-to-One and One-to-Many relationships need to have the appropriate foreign keys created in the database:

/* Example of mySQL script with relationships */

CREATE TABLE IF NOT EXISTS `books` (
    `id` INT(25) UNSIGNED NOT NULL AUTO_INCREMENT,
    `title` varchar(255) NOT NULL,
    `author` varchar(255) NOT NULL,
    `publisher_id` INT(25) NOT NULL, 
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, 
    PRIMARY KEY (`id`), 
    CONSTRAINT fk1 FOREIGN KEY (`publisher_id`) REFERENCES `publishers` (`id`) ON UPDATE CASCADE ON DELETE 
    CASCADE
) ENGINE = InnoDB DEFAULT CHARSET = utf8;

• Many-to-Many relationships that require creating a pivot table in relational databases DO NOT need to be created in the database. The framework will automatically do that upon the definition of the relationship in the model.
  
  

Learn more about creating MySQL relational databases here

Model Fundamentals

The Model is the entity that interfaces directly with the database tables. Every table from your database that represents an object or an entity in your application that a user could act on needs to have a Model in the framework. For example, the table books needs to be represented by a Book Model in the framework. This framework dictates some conventions around the naming of the primary and foreign keys.

Learn more about naming conventions here

• All the models that you create should be in the /application/models folder. In this folder, you can organize the models to your convenience. If you prefer to have your models in a different folder, you can always do that for as long as it is within the /application folder.
• There is no formal naming convention for the Model. We do recommend that you remain consistent. If you choose to name the models in singular or plural then make sure to do that for all your models.
• All the models that you create should extend the Model class

use Caligrafy\Model;

class Book extends Model {
    // your code goes here
}

• The models that you create need to have all the equivalent table attributes represented as properties

use Caligrafy\Model;

class Book extends Model {
    // properties
    public $id;
    public $title;
    public $author;
    public $publisher_id;
    public $created_at;
}

Interfacing with the Model

The Model class exists in the context of a Controller. In other words, you can interface with a model from within a Controller.

Learn more about Controllers here

Instantiating a Model

In order to instantiate the model that was created in the previous section, it needs to be done from the controller by associating the controller with the model and its respective table.

/* Notice that this needs to be done in the Controller */

use Caligrafy\Controller;

class BookController extends Controller {
   public function index()
   {
      $this->associate('Book', 'books'); // associate the controller with a model and a table 

      // the controller could act on the model using the model property
      dump($this->model);

   }
}

Model Methods

There are several built-in methods and properties that can be used from the moment you instantiate a model

/* Associations */
public $table; // retrieves the table name associated with the model
public function associate($table); // returns the Model with a database table associated to it

/* CRUD methods */
public function all($args = null); // Returns all unless an array of condition, order and limit are specified to complete the query
public function find($id); // returns a Model of the specific entry if available
public function search(String $scope, Array $keywords); // searches a table column (scope) for a collection of keywords (array)
public function create($input); // takes an array of values or an object and adds an entry to the respective table in the database
public function update($inputs, $id); // updates an entry in the database with the new values from array or Model
public function delete($id); // deletes a specific entry from the database
public function save(); // saves a the model into the database. If the model has an id defined then it will update otherwise it will create a new entry in the table

/* Relationships definition */

// One-to-One relationship 
public function hasOne($modelName, $joinedTableName, $foreignKey = null, $localKey = null)

// One-to-Many relationship
public function hasMany($modelName, $joinedTableName, $foreignKey = null, $localKey = null)
public function belongsTo($modelName, $joinedTableName, $foreignKey = null, $localKey = null)

// Many-to-Many relationship in both directions
public function belongsToMany($modelName, $joinedTableName, $foreignKeyLocal = null, $foreignKeyJoin = null)

Next Section: Learn about Relationships