It is highly recommended that you use flightphp/active-record instead of this library. No further development will be done with this library, but it does work as it is right now.
Super model is a very simple ORM type php class to easily interact with tables in a database without writing a ton of SQL code all over the place.
To prove it, here are the lines of code...
$ cloc src/
1 text file.
1 unique file.
0 files ignored.
github.com/AlDanial/cloc v 1.74 T=0.01 s (71.8 files/s, 48768.5 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
PHP 1 86 246 347
-------------------------------------------------------------------------------
This is written with performance in mind. So while it will not satisfy every single requirement in every project that's ever been built, it will work in the majority of cases, and do a kick butt job at it too!
Getting started with Super Model is easy, simply extend the super model class and define a table name. That's about it.
<?php
use n0nag0n\Super_Model;
class User extends Super_Model {
protected $table = 'users';
}Now what about some simple examples of how she works?
First, lets assume the following table:
Table: users
---------------------------------------------------------
| id | email | company_id |
| 1 | hi@example.com | 50 |
| 2 | another@example.com | 61 |
| 3 | whatever@example.com | 61 |
---------------------------------------------------------
<?php
// somefile.php
$pdo = new PDO('sqlite::memory:', '', '', [ PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC ]);
$User = new User($pdo);
// WHERE company_id = 50
$users = $User->getAllBycompany_id(50);
// same as above
$users = $User->getAll([ 'company_id' => 50 ]);Easy peasy, lemon squeezy right?
This is a method that returns one row back from the value specified. The * part of the method refers to a field in the database. The field name is case-sensitive to whatever your field name is on your database table.
// get by the id field on the users table
$User->getByid(3);
/*
[
'id' => 3,
'email' => 'whatever@example.com',
'company_id' => 61
]
*/
$User->getBycompany_id(61);
/*
// it only will pull the first row, not all rows
[
'id' => 2,
'email' => 'another@example.com',
'company_id' => 61
]
*/This is a shortcut filter to return all rows by a given value. The * part of the method refers to a field in the database. The field name is case-sensitive to whatever your field name is on your database table.
// this is pointless, but will still work
$User->getAllByid(3);
/*
[
[
'id' => 3,
'email' => 'whatever@example.com',
'company_id' => 61
]
]
*/
$User->getAllBycompany_id(61);
/*
[
[
'id' => 2,
'email' => 'another@example.com',
'company_id' => 61
],
[
'id' => 3,
'email' => 'whatever@example.com',
'company_id' => 61
]
]
*/This is the filter where you can add a bunch of customization to filter the data from your table. There are a few unique keys to be aware of and some operators to help you pull your specific data.
// Full example
$filters = [
//
// arguments in the WHERE statement
//
'some_field' => 5, // some_field = ?
'some_field-=' => 5, // some_field = ?
'another_field' => 'IS NULL', // some_field IS NULL
'another_field' => 'IS NOT NULL', // some_field IS NOT NULL
'another_field->' => 'Apple', // another_field > ?
'another_field->=' => 'Apple', // another_field >= ?
'another_field-<' => 'Apple', // another_field < ?
'another_field-<=' => 'Apple', // another_field <= ?
'another_field-!=' => 'Apple', // another_field != ?
'another_field-<>' => 'Apple', // another_field <> ?
'another_field-LIKE' => 'Ap%ple', // another_field LIKE ?
'another_field-NOT LIKE' => 'Apple%', // another_field NOT LIKE ?
'another_field-IN' => [ 'Apple', 'Banana', 'Peach' ], // another_field IN(??) double question mark gets parsed as array
'another_field-NOT IN' => [ 'Apple', 'Banana', 'Peach' ], // another_field NOT IN(??) double question mark gets parsed as array
// If you need some custom action
'another_field-RAW-> DATE_SUB(?, INTERVAL 1 DAY)' => '1980-01-01', // another_field > DATE_SUB(?, INTERVAL 1 DAY)
//
// Other parts of the query
//
// choose what columns you want to select
'select_fields' => 'id, first_name',
// Get any joins
'joins' => [ 'LEFT JOIN companies ON companies.id = users.company_id' ],
// Group by
'group_by' => 'company_id',
// having
'having' => 'count > 5',
// order by
'order_by' => 'id DESC',
// limit
'limit' => 15,
// offset
'offset' => 10000,
];
$users = $User->getAll($filters);There are also some basic config options with the model properties.
If you have a model that you know will always return a small result set and want to be able to query the entire table, set this property. Otherwise it is a protection so that if no sql params were supplied, you wouldn't retrieve back the entire result set (which could crash and burn many things).
use n0nag0n\Super_Model;
class User extends Super_Model {
protected $table = 'users';
protected $disallow_wide_open_queries = false;
}This will create a single row on the table, but if you supply a multi-dimensional array, it will insert multiple rows. A primary key of id is assumed.
$User->create([ 'email' => 'onemore@example.com', 'company_id' => 55 ]);
// returns 4
$User->create([ [ 'email' => 'ok@example.com', 'company_id' => 55 ], [ 'email' => 'thanks@example.com', 'company_id' => 56 ] ]);
// returns 6, only the last id will be returnedThis will create a single row on the table, but if you supply a multi-dimensional array, it will insert multiple rows. A primary key of id is assumed.
$User->update([ 'id' => 1, 'email' => 'whoneedsemail@example.com' ]);
// returns 1 and will only update the email field
$User->update([ 'email' => 'whoneedsemail@example.com', 'company_id' => 61 ], 'email');
// returns 1
$User->update([ 'company_id' => 61, 'email' => 'donotreply@example.com' ], 'company_id');
// returns 3, not really logical, but it would update all the emailsWhat if you want an automated way to alter your result if a specific flag is fired?
Easy peasy. There is a method called processResult() that will run through every result you pull back. You inject special filters for this method in the $filters['processResults'] key.
<?php
use n0nag0n\Super_Model;
class User extends Super_Model {
protected $table = 'users';
public processResult(array $process_filters, array $result): array {
// add some trigger here and do whatever checks you need
if(isset($process_filters['set_full_name']) && $process_filters['set_full_name'] === true && !empty($result['first_name']) && !empty($result['last_name'])) {
$result['full_name'] = $result['first_name'].' '.$result['last_name'];
}
return $result;
}
}
// later on in some other file.
$User = new User($pdo);
// setting the processResults filter here is the key to connecting the getAll statement with your processResult method
$users = $User->getAll([ 'company_id' => 51, 'processResults' => [ 'set_full_name' => true ] ]);
echo $users[0]['full_name']; // Bob SmithWhat if you need to do a crazy complex SQL query that doesn't fall in the realm of this class or the getAll() filters?
Remember the point of this class is NOT to satisfy every requirement from every project that ever has or will exist, but it will get you 90% the way there. In light of that, there is a simple way to execute the above question. Just use RAW SQL for your one off.
<?php
use n0nag0n\Super_Model;
class User extends Super_Model {
protected $table = 'users';
public function processCrazyKukooQuery(/* add whatever required fields you need */): array {
$db = $this->getDbConnection();
// shamelessly ripped from StackOverflow
$statement = $db->prepare("SELECT
DISTINCT
t.id,
t.tag,
c.title AS Category
FROM
tags2Articles t2a
INNER JOIN tags t ON t.id = t2a.idTag
INNER JOIN categories c ON t.tagCategory = c.id
INNER JOIN (
SELECT
a.id
FROM
articles AS a
JOIN tags2articles AS ta ON a.id=ta.idArticle
JOIN tags AS tsub ON ta.idTag=tsub.id
WHERE
tsub.id IN (12,13,16)
GROUP BY a.id
HAVING COUNT(DISTINCT tsub.id)=3
) asub ON t2a.idArticle = asub.id");
$statement->execute();
return $statement->fetchAll();
}
}
Simply run composer test to run phpunit and phpstan. Currently at 100% coverage and that's where I'd like to keep it.
A note about 100% coverage: While the code may have 100% coverage, actual coverage is different. The goal is to test many different scenarios against the code to think through the code and anticipate unexpected results. I code to "real" coverage, not "did the code run" coverage.