Modeling principle

ORM DataModel has one important specificity. Its main function and purpose is not only to map classes to database tables. ORM DataModel operates on entire entities that consist of multiple classes and therefore database tables. Thus, a whole entity consists of one main entity and its subentities, which may have additional subentities of their own. Such an entity can then be treated as a single entity. An entire entity consisting of multiple tables can be loaded and automatically instantiated simply by a single operation, as well as deleted and stored. Of course, it remains possible to operate only on partial subentities.

Between entities forming a single entity, there are so-called internal relations. However, within ORM it is possible to link these entities together to create external relations.

Let's show it right away with an example. As an example, let's use the entity invoice. The invoice data model consists of the following parts:

General information about the invoice - main entity
That is, an entity including general information about the invoice such as its number, date of issue, customer information, due date, and so on ...
Invoice items - subentity in relation 1:N to the main entity
Each invoice has items. About each item it is necessary to know its description, price per unit, number of units (pieces, hours and so on), VAT rate, VAT breakdown and so on.
Information about invoice payments - subentity in the 1:N relation to the main entity
It is also necessary to record the payment and/or reimbursement of the invoice, their amounts, forms of payment and so on.

On the diagram it would look like this:

As you can see, the invoice consists of at least three classes and three database tables to which these classes are mapped. However, the Jet ORM DataModel can look at an invoice as a single entity. As a whole, it can retrieve, instantiate and, of course, store it. This is all done using a system of internal relations.

It is important to emphasize that the structure of such an entity can actually have any number of subentities and their embeddings. Thus, even a subentity can have its own subentities. For example, the items of an invoice could have other subentities, and those other subentities could have other subentities, and so on. For example, like this:

The only condition is that all subentities of all levels know the identification of the main entity to which they belong. So in our example, this would be the invoice ID. See the section internal sessions.

V praxi se pak s fakturou operuje například takto:


$invoice = Invoice::load( [ 'invoice_id' => $invoice_id ] );

$invoice->addPayment( $new_payment_info );  

$invoice->setIsPaid( true );

$invoice->save();

Or like this:


$invoice = Invoice::load( [ 'invoice_id' => $invoice_id ] );

foreach( $invoice->getItems() as $item ) {

    //do something with the item

}

Of course, in practice, only internal relations are not enough. In practice, our imaginary invoice is bound to other entities.

Let's stay with our invoice example. In addition to invoices, such a system will also include a list of customers and clients. This list of customers will also include a list of contact persons. Again, the customer will be the main entity and the contacts linked to it will be the sub-entity bound by the internal relation and all this will again form a single entity.

However, this whole entity defining the customer and his contacts must of course be linked to the whole invoice entity as follows:

This is made possible by a mechanism within the Jet ORM DataModel called external relations.

Thanks to this mechanism, it is then possible to easily retrieve instances of entire invoices, for example, based on the customer's contact email:


$invoices = Invoice::fetchInstances( ['customers_contacts.email'=>$email] );