README

LeanOrm

A light-weight, highly performant PHP data access library. Good alternative to Doctrine & Eloquent without all the bells & whistles that are not needed in most applications.

Installation Requirements

PHP 8.2+ for version 6.x & 7.x

PHP 8.1+ for versions 4.x & 5.x

PHP 7.4+ for versions 2.x & 3.x

Composer

Versions 2.x & 3.x of this package have been rigorously tested against sqlite 3.7.11+, MySQL 8.0.29+ & PostgreSQL 15.1+.

Version 4.x & 5.x have been rigorously tested against:

• Sqlite 3.34.1+
• MariaDB 10.4.33+, 10.5.24+, 10.6.17+, 10.11.7+, 11.0.5+, 11.1.4+, 11.2.3+ & 11.4.2+
• MySQL 5.6.51, 5.7.44, 8.0.36+, 8.1.0, 8.2.0, 8.3.0+ & 8.4+
• PostgreSQL 12.18+, 13.14+, 14.11+, 15.6+ & 16.2+
• See run-tests-against-multiple-db-versions.php

Version 6.x & 7.x have been rigorously tested against:

• Sqlite 3.46.1
• MariaDB 10.4.34, 10.5.29, 10.6.25, 10.11.16, 11.4.10, 11.8.6 & 12.2.2
• MySQL 5.6.51, 5.7.44, 8.0.45, 8.4.8 & 9.6.0
• PostgreSQL 12.22, 13.23, 14.22, 15.17, 16.13, 17.9 & 18.3
• See run-tests-against-multiple-db-versions.php & run-tests-against-multiple-db-versions-docker.php

MS SQL Server, is theoretically supported but hasn't been tested. Will provide more updates on MS SQL Server support once testing on that DB engine has been done.

If you are using Sqlite, version sqlite 3.7.11 or higher is required.

Version 1.x of this package never got a stable release.

Version 2.x+ of this package is stable & uses aura/sqlquery 2.8.0+ .

Version 3.x+ and higher of this package are also stable & use aura/sqlquery 3.0.0+.

Versions 2.x & 3.x mainly differ in the versions of aura/sqlquery their Model::getSelect(): \Aura\SqlQuery\Common\Select returns and 3.x has a few newer features like Model::fetchOneByPkey($id, array $relations_to_include = []): ?\GDAO\Model\RecordInterface.

Deprecated Utils::search2D(...) in 2.x has been removed in 3.x

Version 6.x is not backwards compatible with 7.x.

Version 5.x is not backwards compatible with 4.x.

Version 4.x is not backwards compatible with 3.x.

Versions 2.x, 3.x & 4.x are feature complete as of July 2024, only bug fixes will be applied to those versions.

Installation

composer require rotexsoft/leanorm

There's an accompanying command-line tool that can be used to automatically generate Model, Record & Collection classes for the tables and views in a database. To install this tool, just run the command below. Read the documentation for the tool for more information.

composer require --dev rotexsoft/leanorm-cli

Running Tests

./vendor/bin/phpunit --coverage-text

You can set the environment variable LEANORM_PDO_DSN with a valid $dsn string for pdo e.g. LEANORM_PDO_DSN=sqlite::memory:

• For Postgres, the dsn must include dbname=blog and you should make sure a blog database exists in the Postgres instance. You don't need this for Sqlite, MariaDB or MySql, the database will be programmatically created.

You can set the environment variable LEANORM_PDO_USERNAME with a valid $username string for pdo if needed e.g. LEANORM_PDO_USERNAME=jblow

You can set the environment variable LEANORM_PDO_PASSWORD with a valid $password string for pdo if needed e.g. LEANORM_PDO_PASSWORD=some_password

For example:

LEANORM_PDO_DSN=sqlite::memory: LEANORM_PDO_USERNAME=jblow LEANORM_PDO_PASSWORD=some_password ./vendor/bin/phpunit --coverage-text

LEANORM_PDO_DSN="mysql:host=hostname_or_ip_address" LEANORM_PDO_USERNAME="jblow" LEANORM_PDO_PASSWORD="some_password" ./vendor/bin/phpunit --coverage-text

GDAO Classes & Interfaces

Take a look at the code for the most up to date listing of methods

LeanORM Classes

Take a look at the code for the most up to date listing of methods

• \LeanOrm\Model extends the abstract \GDAO\Model class
• \LeanOrm\Model\Record & \LeanOrm\Model\ReadOnlyRecord both implement \GDAO\Model\RecordInterface
• \LeanOrm\Model\Collection implements \GDAO\Model\CollectionInterface

Documentation

Documentation for the non-stable 1.x version of this package is located at http://rotexsoft.github.io/leanorm/

Documentation for version 2.x version can be found here.

Documentation for version 3.x+ can be found here.

Documentation for version 4.0.x+ can be found here.

Documentation for version 4.1.x+ can be found here.

Documentation for version 5.x+ can be found here.

Documentation for version 6.x+ can be found here.

Documentation for version 7.x+ can be found here.

Please submit an issue (preferably with a pull request) to address mistakes or omissions in the documentation or to propose improvements to the documentation.

Contributing

PHPUnit Tests are set-up to run in a specific order in phpunit.xml.dist.

Yes, the best practice is for tests to run independently of each other, but because there are fair amount of static methods in the DBConnector class, its tests need to be run first before other Test Classes.

New Test files must be manually added to the phpunit.xml.dist file in order for those new tests to run.

Class properties and method parameters and variables are all in snake case (e.g. $some_property_name).

Branching

These are the branches in this repository:

• master: contains code for the latest major version (7.x) of this package.
• 6.x: contains code for the 6.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 5.x: contains code for the 5.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 4.1.x: contains code for the 4.1.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 4.0.x: contains code for the 4.0.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 3.x: contains code for the 3.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 2.2.x: contains code for the 2.2.x versions of this package. Only bug fixes should be added to this branch. This branch is feature complete.
• 1.X: contains code for the 1.X versions of this package. This branch is abandoned.
• gh-pages: contains documentation for the 1.X versions of this package. This branch is abandoned.