Database

ORM (Object-Relational Mapping)

What is an ORM?

An ORM is a development tool that acts as an intermediary between a DBMS and an OOP language. Its main purpose is to simplify the process of interacting with a database. Using an ORM allows you to focus on writing code, avoiding the complexity, time-consuming writing and maintaining SQL code.

Illuminate\Database

As ORM Monti uses Laravel's Illuminate\Database component, you can find the official documentation at the following links:

• Eloquent documentation on the official website;
• Query builder documentation on the official website;
• Laravel API on the official API website;

The interface for accessing the ORM is the \App\System\Database class (or via the alias \DB), which encapsulates Illuminate\Database and offers some shortcut methods. You can find all the details by consulting the Monti API.

Manage connections

The connections.php configuration file

Connections config is located in /config/connections.php. Each connection has a name that is defined by the array key, and a value that contains the connection parameters.

<?php
    return [
        // mandatory if your project requires a database
        "default" => [
            "driver" => "mysql",
            "host" => "localhost",
            "database" => "database_name",
            "username" => "database_user",
            "password" => "database_password",
            "charset" => "utf8mb4",
            "collation" => "utf8mb4_general_ci",
        ],
        "another_connection" => [
            "driver" => "...",
            "host" => "...",
            ...
        ]
    ];

Add a connection

In addition to being able to add a connection from the configuration files, it is possible to use the addConnection method. The first argument is an array containing the connection configuration, the format is the same as the configuration files. The second represents the connection name.

\DB::addConnection([
    "driver" => "mysql",
    "host" => "localhost",
    "database" => "database_name",
    "username" => "database_user",
    "password" => "database_password",
    "charset" => "utf8mb4",
    "collation" => "utf8mb4_general_ci",
], "connection_name");

Select a connection

You can switch connections with the connection method.

\DB::connection("default")->table(...);
\DB::connection("connection_name")->table(...);

Check if a connection exists

To verify the existence of a connection you can use the hasConnection method, which will return true or false.

\DB::hasConnection("connection_name");

if(\DB::hasConnection("connection_name")) {
    ...
}

For further information on connections and how they work you can consult the documentation and the official Laravel API and the Monti API.

Check if a table exists

You can check whether a table exists on a given connection with the tableExists method, which returns true or false.

\DB::tableExists("reviews");
//optionally specify the connection (defaults to "default")
\DB::tableExists("reviews", "another_connection");

Transactions

You can wrap a block of code inside a database transaction using the transaction method. The closure receives a stdClass object as its first argument, used to communicate the result back to the caller. The second (optional) argument is the connection to use (defaults to "default").

$transaction = \DB::transaction(function($transaction) {
    $review = new Review();
    $review->evaluation = 5;
    $review->comment = "Great!";
    //the closure must explicitly return true on success
    return $review->save();
});

if($transaction->result) {
    // everything went as expected
}
else {
    // $transaction->error holds the caught exception, if any was thrown
}

The closure must explicitly return true on success: any other return value (including false or nothing) rolls back everything it did. If the closure throws, the transaction is rolled back and the exception is caught and stored in $transaction->error instead of propagating.

For further information you can consult the official Laravel API and the Monti API.