Data Model, Fields, Usages, Constraints, and Data Adaptation¶
The eQual framework uses a sophisticated structure for type and value adaptation to manage data consistently and flexibly.
Values are associated with specific types and usages, with constraints and adaptation mechanisms to ensure data integrity and validity throughout their lifecycle.
Entity Definition¶
Entities are defined by inheriting from a base class called Model. This base class structures the data into various fields (Field).
Fields : Type, Content-Type & Usage¶
Each type is associated with a generic content type, which allows both finding an equivalent in all languages and contexts, and associating a signature (schema) ensuring adequate storage and compatibility of data conversions between different languages.
Usages are extensions of content types, allowing for increased precision in storage allocation, and also enable automatic association of formats, syntaxes, validation constraints, and rendering modes according to contexts.
- Types: The types handled by the ORM are limited to scalar and relational types such as
string,boolean,integer,float,date,datetime,time,binary,array,many2one,one2many,many2many. - Content-Types: Each type is linked to a specific content-type, as shown in the provided equivalence (e.g.,
booleanis associated withnumber/boolean). - Usages: A usage is an extension of the content-type that includes additional information and constraints, such as size or specific standards (e.g.,
number/integer:9for integers with a maximum size of 9 digits).
Examples¶
Native PHP type: "double"
| SQL Adapter | Content-Type | Conversion Type |
|---|---|---|
| equal\data\adapt\adapters\sql\DataAdapterSqlRealMySql | number/real | DECIMAL(integer_part,decimal_part) |
| equal\data\adapt\adapters\sql\DataAdapterSqlSqlSrv | number/real | float(24) |
Native PHP type: "bool"
| SQL Adapter | Content-Type | Conversion Type |
|---|---|---|
| equal\data\adapt\adapters\sql\DataAdapterSqlRealMySql | number/boolean | TINYINT |
| equal\data\adapt\adapters\sql\DataAdapterSqlSqlSrv | number/boolean | BOOLEAN |
Usages, Syntaxes & Formats Examples
| Usage | Syntax | Example |
|---|---|---|
| ISBN | urn/isbn.10 | urn/isbn.10 |
| Integer with Size | number[size]/integer:precision | number[3]/integer:2 |
| Language (ISO 639) | language/iso-639:length | language/iso-639:3 |
| Real Number with Precision | number/real:precision.scale | number/real:5.2 |
| Date with Weekday | date/weekday.mon:format | date/weekday.mon:short |
Types equivalence with Content-Types:¶
| Type | Content-Type |
|---|---|
| boolean | number/boolean |
| integer | number/integer |
| float | number/real |
| string | text/plain |
| date | date/plain |
| datetime | date/datetime |
| time | time/plain |
| binary | binary/plain |
| many2one | number/natural |
| one2many | array |
| many2many | array |
| array | array |
Type equivalence with Usages:¶
Content Types et Formats¶
| Type | Content Type |
|---|---|
| boolean | number/boolean |
| integer | number/integer:9 |
| float | number/real:10.2 |
| string | text/plain:255 |
| date | date/plain |
| datetime | date/time |
| time | time/plain |
| binary | binary/plain:64000000 |
| many2one | number/integer:9 |
| one2many | array |
| many2many | array |
| array | array |
Constraints and Data Validation¶
The Field class provides a method getConstraints() to retrieve constraints specific to the type and usage of the field:
- Field getConstraints Method: This method calls the getConstraints method of the usage associated with the field to obtain the constraints.
- Value Validation: When values are associated with a usage, their validity is checked via the usage's getConstraints method.
Data Adaptation¶
Data adaptation is performed via a Service Data Adapter Provider, which allows converting values from one format to another based on their usage:
- Supported Formats: Specific supported formats include application/json, application/sql, and text/plain.
- Data Adapter: The Data Adapter uses the **adaptIn() and adaptOut() ** methods to convert values. For example, a date timestamp can be converted into different output formats (JSON, SQL, text).
Type Adaptation¶
The Field class has a method getContentType to find the content-type associated with the field's type. This content-type is then used to adapt the type from one format to another via:
- **castTypeIn() and castTypeOut() ** methods: These methods allow converting data types according to the target format, ensuring that the data is correctly interpreted based on the context of its use.
For instance a field with a text/plain:255 Usage would be stored in MySQL as varchar(255), while a field with a text/plain:255 Usage would be stored using a mediumtext or a longtext.
Adaptation Example¶
Consider the example of converting a date timestamp (1717960331) into different formats:
- application/json: 2024-06-09T19:12:11.000Z
- application/sql: 2024-06-09 21:12:11
- text/plain: Sunday, June 09, 2024 9:12 PM or Dimanche 09 Juin 2024 21h12 (depending on the locale)
This demonstrates how values can be adapted according to their usages and target formats, ensuring flexible and consistent data management in the Equal framework.
Key takeaways¶
- The objects manipulated in controllers and classes contain values using PHP types.
- Collections can be exported by recursively converting the values during export (
get()):adapter->adaptOut($value, $f->getUsage())
Non-exhaustive list of supported Usages :
text/plain
text/html
amount/money:4
amount/money:4
amount/percent
amount/rate
numeric/hexadecimal:1
numeric/integer
numeric/integer:3
image/jpeg
email
phone
password
password/nist
date/month
date/year
date/year:4
country/iso-3166:2
language/iso-639
uri/url
uri/urn.iban
uri/urn.ean