Skip to content

Commit 70a7a87

Browse files
ratajsratajs
committed
Update README
1 parent f8a47e0 commit 70a7a87

3 files changed

Lines changed: 144 additions & 183 deletions

File tree

‎README.md‎

Lines changed: 139 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,82 @@
11
# SuperSQL
2-
SuperSQL is an easy-to-use powerful SQL query builder for SQLite and MySQL.
2+
SuperSQL is an easy-to-use, yet powerful SQL query builder for SQLite and MySQL.
33

44
## Requirements
5-
* PHP 5.6+
5+
* PHP 7+
66
* PDO SQLite / MySQL driver
77

88
## Setup
9-
* Download the <em>ssql.php</em> file ([https://raw.githubusercontent.com/ratajs/SuperSQL/2.2/ssql.php](https://raw.githubusercontent.com/ratajs/SuperSQL/2.2/ssql.php))
9+
* Download the <em>ssql.php</em> file ([https://raw.githubusercontent.com/ratajs/SuperSQL/2.3/ssql.php](https://raw.githubusercontent.com/ratajs/SuperSQL/2.3/ssql.php))
1010
* Include the file with `include` / `require`
1111

1212
## Examples
13-
Let’s have a table “<strong>users</strong>” with 5 columns: `uid`, `username`, `password`, `sign_up_time` and `nickname`
13+
Let’s have a table ‘<strong>users</strong>’ with 5 columns: `uid`, `username`, `password`, `sign_up_time` and `nickname`
1414

1515
```php
1616
<?php
17-
include "ssql.php";
18-
19-
//Connect with new Ssql($host[, $user[, $password[, $database]]])
20-
$ssql = new Ssql("localhost", "root", "root", "db"); // MySQL
21-
22-
//Connect to SQLite with just the first parameter
23-
$ssql = new Ssql("db.sqlite3");
24-
25-
//To execute raw SQL query use $ssql->q($q[, $a]), FETCH_ALL returns an array of rows, FETCH_OBJECT and FETCH_ARRAY return one row per call
26-
$ssql->q("SELECT * FROM users")->fetch(SQ::FETCH_ALL);
27-
28-
//You can use wildcards for escaping
29-
$ssql->q("SELECT * FROM users WHERE `username`=%0 OR `nickname`=%1", [$name, $nick])->fetch();
30-
31-
//You can set the object‐wide $debug property to print all queries before being executed
32-
$ssql->debug = true;
33-
34-
//You can use queries as methods
35-
$ssql->getUser = "SELECT * FROM users WHERE `username`=%0 OR `nickname`=%1";
36-
$user = $ssql->getUser($name, $nick)->fetch();
37-
38-
//For simple requests use $ssql->read($table[, $cond][, $flags])
39-
//Read function uses FETCH_SMART as default (FETCH_OBJECT for one row, FETCH_ALL for more), so you need to use the FETCH_ALL flag to return an array even when there is only one result
40-
$users = $ssql->read("users", SQ::FETCH_ALL);
41-
$user = $ssql->read("users", ['uid' => $id]);
42-
43-
//You can use the DEBUG flag to print this query before execution
44-
$user = $ssql->read("users", ['uid' => $id], SQ::DEBUG);
45-
46-
//You can use more conditions
47-
$user = $ssql->read("users", ['username' => $name, 'password' => $pass]);
48-
49-
//You can use the COND_OR flag for OR operator instead of AND
50-
$user = $ssql->read("users", ['username' => $name, 'nickname' => $nick], SQ::FETCH_ALL | SQ::COND_OR)[0];
51-
52-
//You can use custom conditions
53-
$users = $ssql->read("users", "`sign_up_time` > " . bcsub(time(), 3600));
54-
55-
//You can use more of them
56-
$users = $ssql->read("users", ["`sign_up_time` > " . bcsub(time(), 3600), "`nickname` IS NOT NULL"], SQ::FETCH_ALL);
57-
58-
//For more complicated requests use $ssql->select($table[, $order[, $cols[, $limit[, $flags]]]]), you can use array keys for aliases
59-
$users = $ssql->select("users", "sign_up_time", ['id' => "uid", 'name' => "username", "sign_up_time", "nickname"], NULL, SQ::ORDER_DESC)->fetch(SQ::FETCH_ALL);
60-
61-
//Or $ssql->selectWhere($table, $cond[, $order[, $cols[, $limit[, $flags]]]])
62-
$user = $ssql->selectWhere("users", ['uid' => $id], "name", ['id' => "uid", 'name' => "username", "sign_up_time", 'nick' => "nickname"])->fetch();
63-
64-
//To quickly display tables use ->dump()
65-
$ssql->select("users")->dump();
66-
67-
//Insert with $ssql->insert($table, $values[, $flags])
68-
$ssql->insert("users", [$id, $name, $pass, time(), NULL]);
69-
70-
//You can use array keys as col names
71-
$ssql->insert("users", ['username' => $name, 'password' => $pass, 'sign_up_time' => time()]);
72-
73-
//You can use INSERT_RETURN_ID flag for returning the first auto increment col value (depends on the database type)
74-
$id = $ssql->insert("users", ['username' => $name, 'password' => $pass, 'sign_up_time' => time()], SQ::INSERT_RETURN_ID);
75-
76-
//Use $ssql->update($table, $cond, $values[, $flags]) to update rows
77-
$ssql->update("users", ['id' => $id], ['nickname' => $nick]);
78-
79-
//You can delete rows with $ssql->delete($table, $cond[, $flags])
80-
$ssql->delete("users", ['id' => $id]);
81-
82-
//You can use $ssql->put($table, $data[, $cond][, $flags]) for inserting, updating and deleting as well
83-
//Insert
84-
$ssql->put("users", [$id, $name, $pass, time(), NULL]);
85-
$ssql->put("users", ['username' => $name, 'password' => $pass, 'sign_up_time' => time()], SQ::INSERT_RETURN_ID);
86-
//Update
87-
$ssql->put("users", ['nickname' => $nick], ['id' => $id]);
88-
//Delete
89-
$ssql->put("users", NULL, ['id' => $id]);
90-
91-
//Use $ssql->truncate($table[, $flags]) to delete all rows in a table
92-
$ssql->truncate("users");
17+
include "ssql.php";
18+
19+
//Connect to MySQL with new SSQL($host[, $user[, $password[, $database]]])
20+
$ssql = new SSQL("localhost", "root", "root", "db");
21+
22+
//Connect to SQLite with just the first argument
23+
$ssql = new SSQL("db.sqlite3");
24+
25+
//Use $ssql->q($q[, $a]) to execute a raw SQL query
26+
$ssql->q("SELECT * FROM `users`");
27+
28+
//You can use wildcards for escaping
29+
$ssql->q("SELECT * FROM `users` WHERE `username`=%0 OR `nickname`=%1", [$name, $nick]);
30+
31+
//You can use queries as methods
32+
$ssql->getUser = "SELECT * FROM `users` WHERE `username` = '%0' OR `nickname` = '%1'";
33+
$user = $ssql->getUser($name, $nick);
34+
35+
//Use $ssql->read($table[, $cond][, $flags]) for simple reading
36+
$users = $ssql->read("users"); // Access the username of a specific user with $users[$index]->username
37+
$users = $users->data(); // If you need a raw array, for example for json_encode($users)
38+
$user = $ssql->read("users", ['uid' => $id]); // You can access the username with $user->username if only one result is returned
39+
40+
//You can use the DEBUG flag to print this query before execution
41+
$user = $ssql->read("users", ['uid' => $id], SQ::DEBUG);
42+
43+
//Or you can set the object‐wide $debug property to print all queries
44+
$ssql->debug = true;
45+
46+
//You can use more conditions
47+
$user = $ssql->read("users", ['username' => $name, 'password' => $pass]);
48+
49+
//You can use the COND_OR flag to use the OR operator instead of AND
50+
$user = $ssql->read("users", ['username' => $name, 'nickname' => $nick], SQ::COND_OR)[0];
51+
52+
//You can use custom conditions
53+
$users = $ssql->read("users", "`sign_up_time` > " . bcsub(time(), 3600));
54+
55+
//You can use more of them
56+
$users = $ssql->read("users", ["`sign_up_time` > " . bcsub(time(), 3600), "`nickname` IS NOT NULL"]);
57+
58+
//Use $ssql->get($table[, $options][, $flags]) for more complex data retrieval
59+
$users = $ssql->get("users", ['order' => "sign_up_time", 'cols' => ['id' => "uid", 'name' => "username", "sign_up_time", "nickname"], 'limit' => 10], SQ::ORDER_DESC);
60+
$user = $ssql->get("users", ['cond' => ['uid' => $id], 'order' => "name", 'cols' => ['id' => "uid", 'name' => "username", "sign_up_time", 'nick' => "nickname"]]);
61+
62+
//You can print the result of a ->read() or ->get() call as an HTML table
63+
print $ssql->read("users");
64+
65+
//Insert with $ssql->put($table, $values[, $flags])
66+
$ssql->put("users", [$id, $name, $pass, time(), NULL]);
67+
68+
//You can use array keys as col names
69+
$ssql->put("users", ['username' => $name, 'password' => $pass, 'sign_up_time' => time()]);
70+
71+
//You can use INSERT_RETURN_ID flag for returning the first auto increment col value (depends on the database type)
72+
$id = $ssql->put("users", ['username' => $name, 'password' => $pass, 'sign_up_time' => time()], SQ::INSERT_RETURN_ID);
73+
74+
//Use $ssql->put($table, $values, $cond[, $flags]) to update rows
75+
$ssql->put("users", ['nickname' => $nick], ['uid' => $id]);
76+
77+
//You can delete rows by supplying NULL to the $values argument
78+
$ssql->put("users", NULL, ['uid' => $id]);
79+
$ssql->put("users", NULL); //Delete all users
9380
?>
9481
```
9582

@@ -104,81 +91,84 @@ Here is list of all SuperSQL flags:
10491
* <b>INSERT_RETURN_ID</b>
10592
* <b>COND_AND</b>
10693
* <b>COND_OR</b>
107-
* <b>FETCH_OBJECT</b>
108-
* <b>FETCH_ARRAY</b>
109-
* <b>FETCH_ALL</b>
110-
* <b>FETCH_SMART</b>
94+
* <b>CASE_INSENSITIVE</b>
11195
* <b>NO_ERROR</b>
11296
* <b>DEBUG</b>
11397

11498
## More examples
11599

116100
```php
117101
<?php
118-
//To use the same database in more projects you can extend the Ssql class
119-
class mySsql extends Ssql {
120-
protected $host = "localhost";
121-
protected $user = "root";
122-
protected $password = "root";
123-
protected $db = "db"; //Optional
124-
};
125-
//And then create an instance
126-
$ssql = new mySsql();
127-
//If $db is not set, you can set it afterwards
128-
$ssql->changeDb("newDB");
129-
130-
131-
//Join
132-
133-
134-
//Use $ssql->selectJoin($table, $join, $on[, $order[, $cols[, $limit[, $flags]]]]) to execute a JOIN command
135-
$result = $ssql->selectJoin("users", "messages", ['from_user' => 'uid'], "time", "*", 5, SQ::ORDER_DESC)->fetch(SQ::FETCH_ALL);
136-
//Use JOIN_LEFT, JOIN_RIGHT and JOIN_FULL flags to other types of JOIN
137-
138-
//To combine JOIN and WHERE use $ssql->selectJoinWhere($table, $join, $on, $cond[, $order[, $cols[, $limit[, $flags]]]])
139-
$result = $ssql->selectJoinWhere("users", "messages", ['from_user' => 'uid'], ['from_user' => $uid])->fetch(SQ::FETCH_ALL);
140-
141-
142-
143-
//Table creation and deletion
144-
145-
146-
//For basic table creation use $ssql->createTable($table, $params[, $primary[, $flags]])
147-
$ssql->createTable("myTable", [
148-
'number' => [ // Column name
149-
'type' => "int", // Column type
150-
'NULL' => false // NULL
151-
],
152-
'text' => [
153-
'type' => "varchar",
154-
'length' => 64, // Max length
155-
'NULL' => true
156-
]
157-
], "number");
158-
159-
//Use $ssql->deleteTable($table[, $flags]) to delete a table
160-
$ssql->deleteTable("myTable");
161-
162-
//To see a list of all tables in your database use $ssql->tableList([$flags])
163-
print_r($ssql->tableList());
164-
165-
166-
//Advanced conditions
167-
168-
169-
//You can use more advanced conditions with $ssql->cond(), this will select users that have the same username and nickname signed up in the last hour
170-
$ssql->read("users", $ssql->cond()->eq("username", "nickname")->gte("sign_up_time", time() - 3600));
171-
172-
//Use arrays to differentiate string values from column names and to specify more alternatives, the COND_OR flag is also supported
173-
//This will select users that have username either "ratajs" or "admin" or that have nickname "RatajS"
174-
$ssql->read("users", $ssql->cond()->eq("username", ["ratajs", "admin"])->eq("nickname", ["RatajS"], SQ::COND_OR));
175-
176-
//->not() negates the condition, this will select users with usernames other than admin
177-
$ssql->read("users", $ssql->cond()->eq("username", ["admin"])->not());
178-
179-
//You can also pass another condition to it, this will select users that don’t have any nickname with username other than "admin" or "root".
180-
$ssql->read("users", $ssql->cond()->eq("nickname", [""])->not($ssql->cond()->eq("username", ["admin", "root"])));
181-
182-
//Supported conditions: ->eq(), ->lt(), ->gt(), ->lte(), ->gte(), ->like(), ->between(), ->begins(), ->ends(), ->contains() and ->in()
102+
//You can extend the SSQL class
103+
class MySSQL extends SSQL {
104+
protected $host = "localhost";
105+
protected $user = "root";
106+
protected $password = "root";
107+
protected $db = "db"; //Optional
108+
};
109+
//And then create an instance
110+
$ssql = new MySSQL();
111+
//If $db is not set, you can set it afterwards
112+
$ssql->changeDb("newDB");
113+
114+
115+
//Join
116+
117+
118+
$result = $ssql->get("users", ['join' => "messages", 'on' => ['from_user' => 'uid'], 'order' => "time", 'limit' => 5], SQ::ORDER_DESC);
119+
//Use JOIN_LEFT, JOIN_RIGHT and JOIN_FULL flags for other types of JOIN
120+
121+
$result = $ssql->get("users", ['join' => "messages", 'on' => ['from_user' => 'uid'], 'cond' => ['from_user' => $uid]]);
122+
123+
124+
125+
//Table creation and deletion
126+
127+
128+
//For basic table creation use $ssql->createTable($table, $params[, $primary[, $flags]])
129+
$ssql->createTable("myTable", [
130+
'number' => [
131+
'type' => "int",
132+
'NULL' => false
133+
],
134+
'text' => [
135+
'type' => "varchar",
136+
'size' => 64,
137+
'NULL' => true
138+
]
139+
], "number"); // Primary key
140+
141+
//Use $ssql->deleteTable($table[, $flags]) to delete a table
142+
$ssql->deleteTable("myTable");
143+
144+
//To see a list of all tables in your database use $ssql->tableList([$flags])
145+
print_r($ssql->tableList());
146+
147+
148+
//Advanced conditions
149+
150+
151+
//You can use more advanced conditions with $ssql->cond(), this will select users that have the same username and nickname signed up in the last hour
152+
$ssql->read("users", $ssql->cond()->eq("username", "nickname")->gte("sign_up_time", time() - 3600));
153+
154+
//Use arrays to differentiate string values from column names and to specify more alternatives, the COND_OR flag is also supported
155+
//This will select users that have username either "ratajs" or "admin" or that have nickname "RatajS"
156+
$ssql->read("users", $ssql->cond()->eq("username", ["ratajs", "admin"])->eq("nickname", ["RatajS"], SQ::COND_OR));
157+
158+
//->not() negates the condition, this will select users with usernames other than admin
159+
$ssql->read("users", $ssql->cond()->eq("username", ["admin"])->not());
160+
161+
//You can also pass another condition to it, this will select users that don’t have any nickname with username other than "admin" or "root".
162+
$ssql->read("users", $ssql->cond()->eq("nickname", [""])->not($ssql->cond()->eq("username", ["admin", "root"])));
163+
164+
//Supported conditions: ->eq(), ->lt(), ->gt(), ->lte(), ->gte(), ->like(), ->between(), ->begins(), ->ends(), ->contains() and ->in()
165+
166+
//Transactions
167+
168+
$ssql->beginTransaction();
169+
170+
//...
171+
172+
$ssql->endTransaction(); //Or $ssql->rollBackTransaction()
183173
?>
184174
```

‎ssql.php‎

Lines changed: 3 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,9 @@ abstract class SQ {
4949
const INSERT_RETURN_ID = 64;
5050
const COND_AND = 128;
5151
const COND_OR = 256;
52-
const FETCH_OBJECT = 512;
53-
const FETCH_ARRAY = 1024;
54-
const FETCH_ALL = 2048;
55-
const FETCH_SMART = 4096;
56-
const FETCH_HTML = 8192;
57-
const CASE_INSENSITIVE = 16384;
58-
const NO_ERROR = 32768;
59-
const DEBUG = 65536;
52+
const CASE_INSENSITIVE = 512;
53+
const NO_ERROR = 1024;
54+
const DEBUG = 2048;
6055

6156
static function open(string $host = "", string $user = "", string $password = "", string $db = "", &$object = "return") {
6257
if($object=="return")
@@ -606,30 +601,6 @@ public function get(string $table, $options = [], int $flags = 0) {
606601
$jointype = boolval($flags & self::JOIN_FULL) ? self::JOIN_FULL : (boolval($flags & self::JOIN_RIGHT) ? self::JOIN_RIGHT : (boolval($flags & self::JOIN_LEFT) ? self::JOIN_LEFT : self::JOIN_INNER));
607602
else
608603
$jointype = $options['join_type'];
609-
if($flags & self::FETCH_OBJECT)
610-
$flags-= self::FETCH_OBJECT;
611-
if($flags & self::FETCH_ARRAY)
612-
$flags-= self::FETCH_ARRAY;
613-
if($flags & self::FETCH_ALL)
614-
$flags-= self::FETCH_ALL;
615-
if($flags & self::FETCH_SMART)
616-
$flags-= self::FETCH_SMART;
617-
if($flags & self::COND_AND)
618-
$flags-= self::COND_AND;
619-
if($flags & self::COND_OR)
620-
$flags-= self::COND_OR;
621-
if($flags & self::ORDER_ASC)
622-
$flags-= self::ORDER_ASC;
623-
if($flags & self::ORDER_DESC)
624-
$flags-= self::ORDER_DESC;
625-
if($flags & self::JOIN_INNER)
626-
$flags-= self::JOIN_INNER;
627-
if($flags & self::JOIN_LEFT)
628-
$flags-= self::JOIN_LEFT;
629-
if($flags & self::JOIN_RIGHT)
630-
$flags-= self::JOIN_RIGHT;
631-
if($flags & self::JOIN_FULL)
632-
$flags-= self::JOIN_FULL;
633604
$cond = $options['cond'] ?? false;
634605
$join = $options['join'] ?? false;
635606
$on = $options['on'] ?? false;

‎tests.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@
518518
assert($r[0]->num==16);
519519
assert($r[1]->num==48);
520520

521-
$ssql->q("UPDATE `table3` SET `table3_num` = \"%1\" WHERE `table3_id` = \"%0\"", "3", "42");
521+
$ssql->q("UPDATE `table3` SET `table3_num` = '%1' WHERE `table3_id` = '%0'", "3", "42");
522522
$r = $ssql->read("table3");
523523
assert(count($r)==4);
524524
assert($r[0]->table3_id==1);
@@ -537,7 +537,7 @@
537537
assert(count($r)==1);
538538
assert($r[0]->num==16);
539539

540-
$ssql->inc = "UPDATE `table3` SET `table3_num` = `table3_num` + 1 WHERE `table3_id` = %0";
540+
$ssql->inc = "UPDATE `table3` SET `table3_num` = `table3_num` + 1 WHERE `table3_id` = '%0'";
541541
$ssql->inc(4);
542542
$r = $ssql->read("table3");
543543
assert(count($r)==4);

0 commit comments

Comments
 (0)