You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
### PHPFUI\ORM a minimal Object Relational Mapper (ORM) for MySQL, MariaDB and SQLite3
4
4
Why another PHP ORM? In writing minimal and fast websites, it was determined that existing PHP ORM solutions were overly complex. **PHPFUI\ORM** is less than 6k lines of code in under 50 files. It is designed to have a minimal memory footprint and excellent execution times for most database needs.
5
5
6
6
**PHPFUI\ORM** is not an attempt to write an abstraction around SQL as other ORMs do, rather it is a way to work with SQL that closely matches the semantics of SQL, with the power of PHP objects. It allows PHP to manipulate SQL queries without having to write SQL in plain text. This is very useful for queries generated via user interfaces where the user is given a lot of flexability in how a query is defined.
7
7
8
8
## Features
9
-
-**Active Records** that present a fully type checked object interface and implement basic CRUD functionality.
10
-
-**Active Tables** for full table operations including support for where, having, limits, ordering, grouping, joins and unions.
11
-
-**Data Cursors** that implement **iterable** and **Countable** eliminating the need for full arrays read into memory.
12
-
-**Validation** for fully customizable and translatable backend validation.
13
-
-**Virtual Fields** for get and set semantics.
14
-
-**Migrations** simple migrations offer atomic up and down migrations.
15
-
-**Relations** for parent, children, one to one, many to many, and custom relationships.
16
-
-**Type Safe** to prevent stupid type errors.
17
-
-**Raw SQL Query Support** execute any valid SQL command.
18
-
-**MultiDatabase Support** built on PDO with support for MySQL, MariaDB and SQLite.
9
+
-**Active Records** A fully type checked object interface and implement basic CRUD functionality.
10
+
-**Active Tables** Full table operations including support for where, having, limits, ordering, grouping, joins and unions.
11
+
-**Data Cursors** Cursors implement **iterable** and **Countable** eliminating the need for full arrays read into memory.
12
+
-**Validation** Fully customizable and translatable backend validation.
13
+
-**Virtual Fields** Supports get and set semantics for any custom or calculated field.
14
+
-**Migrations** Simple migrations offer atomic up and down migrations.
15
+
-**Relations** Parent, children, one to one, many to many, and custom relationships.
16
+
-**Transactions** Object based transaction meaning exceptions can not leave an open transacton.
17
+
-**Type Safe** Prevent stupid type errors.
18
+
-**Raw SQL Query Support** Execute any valid SQL command.
19
+
-**Multiple Database Support** Work with multiple databases simultaneously.
20
+
-**Multi-Vendor Support** Built on PDO with support for MySQL, MariaDB and SQLite.
19
21
20
22
## Usage
21
23
### Setup
@@ -108,13 +110,12 @@ Exceptions are generated in the following conditions:
108
110
- Incorrect type for Operator (must be an array for **IN** for example)
109
111
- Passing an incorrect type as a primary key
110
112
- Invalid join type
111
-
- Requesting a **RecordCursor** with a table join
112
113
- Joining on an invalid table
113
114
114
115
All of the above exceptions are programmer errors and strictly enforced. Empty queries are not considered errors. SQL may also return [Exceptions](https://www.php.net/manual/en/class.exception.php) if invalid fields are used.
115
116
116
117
### Type Conversions
117
-
If you set a field to the wrong type, the library logs an error then converts the type via the appropriate PHP cast.
118
+
If you set a field to the wrong type, the library logs an warning then converts the type via the appropriate PHP cast.
118
119
119
120
## Multiple Database Support
120
121
While this is primarily a single database ORM, you can switch databases at run time. Save the value from `$connectionId = \PHPFUI\ORM::addConnection($pdo);` and then call `\PHPFUI\ORM::useConnection($db);` to switch. `\PHPFUI\ORM::addConnection` will set the current connection.
Copy file name to clipboardexpand all lines: docs/2. Active Record.md
+6-1
Original file line number
Diff line number
Diff line change
@@ -131,8 +131,13 @@ $order->insert();
131
131
```
132
132
Notice that we did not have to save the customer record. By assigning it to the order record, it was automatically saved to generate the required primary key value. The related record is not saved if it already has been assigned a primary key, it is your responsiblity to save it if you changed an existing record.
133
133
134
-
### Alternate way to set related records
134
+
### Alternate Way To Set Related Records
135
135
You can always just assign the id's directly: `$orderDetail->purchase_order_id = $purchase_order->purchase_order_id;`. Saving the OrderDetail record is up to you.
136
136
137
137
### Other Types Of Related Records
138
138
See [Virtual Fields](<https://github.com/phpfui/ORM/blob/main/docs/5. Virtual Fields.md>) for information on how to impliment child or many to many relationships.
139
+
140
+
### Multi Database Support
141
+
Related Records will always return a record from the currently selected database. Care must be taken when using multiple databases that any references to related records are done while the correct database instance is active. Cursors will continue to use the database in effect when they were created.
142
+
143
+
A future version of this libray may offer better multi database support.
Copy file name to clipboardexpand all lines: docs/6. Migrations.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -53,8 +53,8 @@ class Migration_1 extends \PHPFUI\ORM\Migration
53
53
```
54
54
Migrations must be inherited from [\PHPFUI\ORM\Migration](http://phpfui.com/?n=PHPFUI%5CORM&c=Migration). They must have the following methods defined:
55
55
-**description**() : string, returns a human readable description of what the migration does.
56
-
-**up**() : bool, performs SQL statements to take the database to the next version.
57
-
-**down**() : bool, reverts the up and leaves the database in the prior version state.
56
+
-**up**() : bool, performs SQL statements to take the database to the next version. Returns true on success.
57
+
-**down**() : bool, reverts the up and leaves the database in the prior version state. Returns true on success.
58
58
59
59
## Running migrations from code
60
60
The [\PHPFUI\ORM\Migrator](http://phpfui.com/?n=PHPFUI%5CORM&c=Migrator) class is used to run migrations automatically. Use the **migrate**() method to go to the latest version, or **migrateTo**() for a specific version. The class handles running migrations in the correct order. The **getStatus**() result should be shown to the user.
Copy file name to clipboardexpand all lines: docs/7. Validation.md
+13-3
Original file line number
Diff line number
Diff line change
@@ -41,13 +41,13 @@ foreach ($validationErrors as $field => $fieldErrors)
41
41
| day_month_year | Loosely formatted date (D-M-Y) | None |
42
42
| domain | Valid domain | None |
43
43
| email | Valid email | None |
44
-
| enum | MySQL enum value, case insensitive | comma separated list of identifiers<br>**Example:** enum:GET,POST,PUT,DELETE|
44
+
| enum | MySQL enum value, case insensitive | comma separated list of identifiers<br>**Example:** enum:Get,Post,Put,Delete|
45
45
| enum_exact | MySQL enum value, case sensitive | comma separated list of identifiers<br>**Example:** enum:ssl,tls |
46
46
| integer | Whole number, no fractional part | None |
47
47
| maxlength | Length must be greater or equal | Optional length, else MySQL limit |
48
-
| maxvalue | Value must be greater or equal |number, required |
48
+
| maxvalue | Value must be greater or equal |value, required |
49
49
| minlength | Must be less than or equal | number, default field size |
50
-
| minvalue | Must be less than or equal |number, required |
50
+
| minvalue | Must be less than or equal |value, required |
51
51
| month_day_year | Loosely formatted date (M-D-Y) | None |
52
52
| month_year | Loosely formatted Month Year | None |
53
53
| number | Floating point number or whole number | None |
@@ -85,3 +85,13 @@ You may need to do additional checks for a specific record type. A second param
85
85
86
86
You can also pass an optional method to validate to perform more complex validation. By default, insert, update, and delete are standard methods that are used by the \App\Controller\Record class will use.
While PHPFUI\ORM supports the traditional beginTransaction(), commit() and rollBack() on the PDO object, it is recommended you use the \PHPFUI\ORM\Transaction class.
3
+
4
+
```php
5
+
$transaction = new \PHPFUI\ORM\Transaction();
6
+
// do some stuff
7
+
if ($allGood)
8
+
{
9
+
$transaction->commit();
10
+
}
11
+
else
12
+
{
13
+
$transaction->rollBack();
14
+
}
15
+
```
16
+
The above creates a transaction on the current database. Commit and rollback will also be called on the correct database even if you are working on another database at the time.
17
+
18
+
The main advantage of a Transaction object, it that will will rollback any changes on a thrown exception assuming the transaction object is properly scoped.
0 commit comments