Skip to content

Commit ce5952d

Browse files
francerzfrancerz
committed
IMP README.md readability parentheses syntax and operators
1 parent 72cff94 commit ce5952d

File tree

1 file changed

+79
-57
lines changed

1 file changed

+79
-57
lines changed

‎README.md‎

Lines changed: 79 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ Table of contents
2121
- [Update query ↑](#update-query-)
2222
- [Delete query ↑](#delete-query-)
2323
- [Build SELECT with WHERE or HAVING clause ↑](#build-select-with-where-or-having-clause-)
24-
- [List of operators ↑](#list-of-operators-)
24+
- [Parentheses syntax](#parentheses-syntax)
25+
- [List of operators ↑](#list-of-operators-)
2526
- [Building SELECT with JOIN ↑](#building-select-with-join-)
2627
- [SUPPORTED JOIN TYPES](#supported-join-types)
2728
- [Examples](#examples)
@@ -34,7 +35,7 @@ Installation [↑](#table-of-contents)
3435

3536
This package can be installed with composer using following command.
3637

37-
```bash
38+
```sh
3839
composer require francerz/sql-builder
3940
```
4041

@@ -125,8 +126,8 @@ Build SELECT with WHERE or HAVING clause [↑](#table-of-contents)
125126
Bellow are examples of using `WHERE` clause which aplies to `SELECT`, `UPDATE`
126127
and `DELETE` queries.
127128

128-
Selecting all fields from table `groups` when the value of column `group_id` is
129-
equal to `10`.
129+
> Selecting all fields from table `groups` when the value of column `group_id` is
130+
> equal to `10`.
130131
131132
```sql
132133
SELECT * FROM groups WHERE group_id = 10
@@ -141,8 +142,8 @@ $query = Query::selectFrom('groups')->where('group_id', 10);
141142

142143
---
143144

144-
Selecting all fields from table `groups` when value of column `group_id` is
145-
equals to `10`, `20` or `30`.
145+
> Selecting all fields from table `groups` when value of column `group_id` is
146+
> equals to `10`, `20` or `30`.
146147
147148
```sql
148149
SELECT * FROM groups WHERE group_id IN (10, 20, 30)
@@ -157,8 +158,8 @@ $query = Query::selectFrom('groups')->where('group_id', [10, 20, 30]);
157158

158159
---
159160

160-
Selecting all fields from table `groups`when value of column `teacher` is
161-
`NULL`.
161+
> Selecting all fields from table `groups`when value of column `teacher` is
162+
> `NULL`.
162163
163164
```sql
164165
SELECT * FROM groups WHERE teacher IS NULL
@@ -173,9 +174,9 @@ $query = Query::selectFrom('groups')->where('teacher', 'NULL');
173174

174175
---
175176

176-
Selecting all fields from table `groups` when value of column `group_id` is
177-
less or equals to `10` and value from column `subject` contains the word
178-
`"database"`.
177+
> Selecting all fields from table `groups` when value of column `group_id` is
178+
> less or equals to `10` and value from column `subject` contains the word
179+
> `"database"`.
179180
180181
```sql
181182
SELECT * FROM groups WHERE group_id <= 10 AND subject LIKE '%database%'
@@ -192,58 +193,73 @@ $query->where('group_id', '<=', 10)->andLike('subject', '%database%');
192193

193194
---
194195

195-
Selecting all fields from table `groups` when the value of `group_id` is equals
196-
to `10` or is within the range from `20` to `30`.
196+
### Parentheses syntax
197+
198+
To incorporate highly specific and intricate conditions, it becomes essential to
199+
override the default operator precedence, a task traditionally achieved through
200+
the use of parentheses in SQL syntax. Within the SQL Builder, this functionality
201+
is adeptly handled through the utilization of an anonymous function parameter.
202+
203+
Parentheses anonymous function works in the following syntax:
204+
205+
```php
206+
$query->where(function($subwhere) { });
207+
$query->where->not(function($subwhere) { });
208+
$query->where->and(function($subwhere) { });
209+
$query->where->or(function($subwhere) { });
210+
$query->where->andNot(function($subwhere) { });
211+
$query->where->orNot(function($subwhere) { });
212+
```
213+
214+
> Selecting all fields from table `groups` when the value of `group_id` is
215+
> equals to `10` or is within the range from `20` to `30`.
197216
198217
```sql
199-
SELECT * FROM groups WHERE (group_id = 10 OR group_id BETWEEN 20 AND 30)
218+
SELECT *
219+
FROM groups
220+
WHERE subject LIKE '%database%'
221+
AND (group_id = 10 OR group_id BETWEEN 20 AND 30)
200222
```
223+
201224
```php
202225
$query = Query::selectFrom('groups');
203226

204227
// Using an anonymous function to emulate parenthesis
205-
$query->where(function(ConditionList $subwhere) {
206-
$subwhere
207-
->equals('group_id', 10)
208-
->orBetween('group_id', 20, 30);
209-
});
228+
$query->where()
229+
->like('subject', '%database%')
230+
->and(function(ConditionList $subwhere) {
231+
$subwhere
232+
->equals('group_id', 10)
233+
->orBetween('group_id', 20, 30);
234+
});
210235
```
211236

212-
> Parenthesis anonymous function works in the following syntax.
213-
>
214-
> ```php
215-
> $query->where(function($subwhere) { });
216-
> $query->where->not(function($subwhere) { });
217-
> $query->where->and(function($subwhere) { });
218-
> $query->where->or(function($subwhere) { });
219-
> $query->where->andNot(function($subwhere) { });
220-
> $query->where->orNot(function($subwhere) { });
221-
> ```
222-
223237
---
224238

225-
#### List of operators [↑](#table-of-contents)
226-
227-
The library has a complete list of operators that are mostly common to every SQL
228-
database engine and to facilitate reading, also prefixes the `and` and `or`
229-
logical operators.
230-
231-
| SQL Operator | Regular (AND) | AND | OR |
232-
| ------------- | ----------------------------- | -------------------------------- | ------------------------------- |
233-
| `=` | `equals($op1, $op2)` | `andEquals($op1, $op2)` | `orEquals($op1, $op2)` |
234-
| `<>` or `!=` | `notEquals($op1, $op2)` | `andNotEquals($op1, $op2)` | `orNotEquals($op1, $op2)` |
235-
| `<` | `lessThan($op1, $op2)` | `andLessThan($op1, $op2)` | `orLessthan($op1, $op2)` |
236-
| `<=` | `lessEquals($op1, $op2)` | `andLessEquals($op1, $op2)` | `orLessEquals($op1, $op2)` |
237-
| `>` | `greaterThan($op1, $op2)` | `andGreaterThan($op1, $op2)` | `orGreaterThan($op1, $op2)` |
238-
| `>=` | `greaterEquals($op1, $op2)` | `andGreaterEquals($op1, $op2)` | `orGreaterEquals($op1, $op2)` |
239-
| `LIKE` | `like($op1, $op2)` | `andLike($op1, $op2)` | `orLike($op1, $op2)` |
240-
| `NOT LIKE` | `notLike($op1, $op2)` | `andNotLike($op1, $op2)` | `orNotLike($op1, $op2)` |
241-
| `IS NULL` | `null($op)` | `andNull($op)` | `orNull($op)` |
242-
| `IS NOT NULL` | `notNull($op)` | `andNotNull($op)` | `orNotNull($op)` |
243-
| `BETWEEN` | `between($op, $min, $max)` | `andBetween($op, $min, $max)` | `orBetween($op, $min, $max)` |
244-
| `NOT BETWEEN` | `notBetween($op, $min, $max)` | `andNotBetween($op, $min, $max)` | `orNotBetween($op, $min, $max)` |
245-
| `IN` | `in($op, $array)` | `andIn($op, $array)` | `orIn($op, $array)` |
246-
| `NOT IN` | `notIn($op, $array)` | `andNotIn($op, $array)` | `orNotIn($op, $array)` |
239+
### List of operators [↑](#table-of-contents)
240+
241+
The library provides a comprehensive array of operators that are largely
242+
consistent across various SQL database engines. To enhance readability, it also
243+
prefixes the `and` and `or` logical operators for clarity.
244+
245+
| Operator | SQL Operator | Regular (AND) | AND | OR |
246+
| ---------------- | ------------- | ----------------------------- | -------------------------------- | ------------------------------- |
247+
| Comparison | `=` | `equals($op1, $op2)` | `andEquals($op1, $op2)` | `orEquals($op1, $op2)` |
248+
| | `<>` or `!=` | `notEquals($op1, $op2)` | `andNotEquals($op1, $op2)` | `orNotEquals($op1, $op2)` |
249+
| | `<` | `lessThan($op1, $op2)` | `andLessThan($op1, $op2)` | `orLessthan($op1, $op2)` |
250+
| | `<=` | `lessEquals($op1, $op2)` | `andLessEquals($op1, $op2)` | `orLessEquals($op1, $op2)` |
251+
| | `>` | `greaterThan($op1, $op2)` | `andGreaterThan($op1, $op2)` | `orGreaterThan($op1, $op2)` |
252+
| | `>=` | `greaterEquals($op1, $op2)` | `andGreaterEquals($op1, $op2)` | `orGreaterEquals($op1, $op2)` |
253+
| Pattern Matching | `LIKE` | `like($op1, $pattern)` | `andLike($op1, $pattern)` | `orLike($op1, $pattern)` |
254+
| | `NOT LIKE` | `notLike($op1, $pattern)` | `andNotLike($op1, $pattern)` | `orNotLike($op1, $pattern)` |
255+
| | `REGEXP` | `regexp($op1, $pattern)` | `andRegexp($op1, $pattern)` | `orRegexp($op1, $pattern)` |
256+
| | `NOT REGEXP` | `notRegexp($op1, $pattern)` | `andNotRegexp($op1, $pattern)` | `orNotRegexp($op1, $pattern)` |
257+
| Nullability | `IS NULL` | `null($op)` | `andNull($op)` | `orNull($op)` |
258+
| | `IS NOT NULL` | `notNull($op)` | `andNotNull($op)` | `orNotNull($op)` |
259+
| Range | `BETWEEN` | `between($op, $min, $max)` | `andBetween($op, $min, $max)` | `orBetween($op, $min, $max)` |
260+
| | `NOT BETWEEN` | `notBetween($op, $min, $max)` | `andNotBetween($op, $min, $max)` | `orNotBetween($op, $min, $max)` |
261+
| Membership | `IN` | `in($op, $array)` | `andIn($op, $array)` | `orIn($op, $array)` |
262+
| | `NOT IN` | `notIn($op, $array)` | `andNotIn($op, $array)` | `orNotIn($op, $array)` |
247263

248264
> **About `ConditionList` class**
249265
>
@@ -297,7 +313,8 @@ $query
297313

298314
---
299315

300-
Using table aliases to reduce naming lenght.
316+
Using table aliases to reduce naming length.
317+
301318
```sql
302319
SELECT * FROM groups AS g INNER JOIN teachers AS t ON g.teacher_id = t.teacher_id
303320
```
@@ -318,6 +335,7 @@ $query
318335
---
319336

320337
Multiple database (same host) select with join.
338+
321339
```sql
322340
SELECT * FROM school.groups AS g INNER JOIN hr.employees AS e ON g.teacher_id = e.employee_id
323341
```
@@ -330,7 +348,8 @@ $query
330348

331349
---
332350

333-
Selecting fields from joined tables
351+
Selecting fields from joined tables.
352+
334353
```sql
335354
SELECT g.group_id, t.given_name, t.family_name
336355
FROM groups AS g
@@ -345,7 +364,8 @@ $query
345364

346365
---
347366

348-
Renaming fields from joined tables
367+
Renaming fields from joined tables.
368+
349369
```sql
350370
SELECT g.group_id, CONCAT(t.given_name, ' ', t.family_name) AS teacher_name
351371
FROM groups AS g
@@ -361,7 +381,8 @@ $query
361381

362382
---
363383

364-
Selecting columns into an external function (cleaner code)
384+
Selecting columns into an external function (cleaner code).
385+
365386
```sql
366387
SELECT g.group_id, CONCAT(t.given_name, ' ', t.family_name) AS teacher_name
367388
FROM groups AS g
@@ -380,7 +401,8 @@ $query->columns([
380401

381402
---
382403

383-
Join tables and subqueries
404+
Join tables and subqueries.
405+
384406
```sql
385407
-- Gets all groups of active teachers
386408
SELECT g.group_id, CONCAT(t.given_name, ' ', t.family_name) AS teacher_name

0 commit comments

Comments
 (0)