Skip to content

Commit cb57b80

Browse files
TheTechsTechTheTechsTech
committed
Update docs/doc-blocks - ready for version release,
1 parent 2b83925 commit cb57b80

File tree

4 files changed

+266
-166
lines changed

4 files changed

+266
-166
lines changed

‎README.md‎

Lines changed: 103 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@
1010

1111
***A class to make it very easy to deal with database connections.***
1212

13-
This is a [WIP] of [__version 5__](https://github.com/ezSQL/ezsql/tree/v5) which will break users of **version 4**.
13+
This is [__Version 5__](https://github.com/ezSQL/ezsql/tree/v5) which will break users of **version 4**.
1414

1515
Mainly by:
16-
- The use of `namespace` in the `global` functions **ezFunctions.php** file.
16+
17+
- The use of `namespace` in the `global` functions **ezFunctions.php** file.
1718
Usage of the **global** functions will require the user to begin a `.php` file something like:
1819

1920
```php
@@ -25,15 +26,16 @@ Mainly by:
2526
inserting,
2627
};
2728
```
28-
- Class properties that was accessible by magic methods `get/set`, now PSR 1 camelCase.
29-
- Renamed `select` of `ez_mysqli` to `dbSelect`.
30-
- Renamed class method and behavior of `selecting` to `select`.
31-
- `selecting`, and new `inserting` methods, can be called without table name, only the other necessary parameters:
32-
- The table *name* with *prefix*, can be preset/stored with methods `tableSetup(name, prefix), or setTable(name), setPrefix(append)`, if called without presetting, `false` is returned.
33-
- This **feature** will be added to **all** database *CRUD* access methods , each method name will have an `ing` ending added.
34-
- Removed global functions where `table` name passed in, use functions using preset table names ending with `ing`.
3529

36-
[__version 4__](https://github.com/ezSQL/ezsql/tree/v4) has many modern programming practices in which will break users of version 3.
30+
- Class properties that was accessible by magic methods `get/set`, now PSR 1 camelCase.
31+
- Renamed `select` of `ez_mysqli` to `dbSelect`.
32+
- Renamed class method and behavior of `selecting` to `select`.
33+
- `selecting`, and new `inserting` methods, can be called without table name, only the other necessary parameters:
34+
- The table *name* with *prefix*, can be preset/stored with methods `tableSetup(name, prefix), or setTable(name), setPrefix(append)`, if called without presetting, `false` is returned.
35+
- This **feature** will be added to **all** database *CRUD* access methods , each method name will have an `ing` ending added.
36+
- Removed global functions where `table` name passed in, use functions using preset table names ending with `ing`.
37+
38+
[__Version 4__](https://github.com/ezSQL/ezsql/tree/v4) has many modern programming practices in which will break users of version 3.
3739

3840
[__Version 3__](https://github.com/ezSQL/ezsql/tree/v3) broke version 2.1.7 in one major way, it required *PHP 5.6*. Which drop mysql extension support, other than that, nothing as far using the library was changed, only additional features.
3941

@@ -138,7 +140,7 @@ prepareOff(); // When off shortcut SQL Methods calls will use vendors escape rou
138140
* `orderBy($orderBy, $order);`
139141
* `limit($numberOf, $offset = null)`
140142
* `where( ...$whereConditions);`
141-
* `selecting(string $table = null, $columnFields = '*', ...$conditions);`
143+
* `select(string $table = null, $columnFields = '*', ...$conditions);`
142144
* `create_select(string $newTable, $fromColumns, $oldTable = null, ...$conditions);`
143145
* `select_into(string $newTable, $fromColumns, $oldTable = null, ...$conditions);`
144146
* `update(string $table = null, $keyAndValue, ...$whereConditions);`
@@ -181,11 +183,18 @@ grouping( eq(key, value, combiner ), eq(key, value, combiner ) )
181183
```
182184

183185
```php
184-
// Supply the the whole query string, and placing '?' within
185-
// With the same number of arguments in an array.
186-
// It will determine arguments type, execute, and return results.
186+
// Note: The usage of this method will require the user/developer to check
187+
// if `query_string` or `param_array` is valid.
188+
//
189+
// This is really an `private` internal method for other shortcut methods,
190+
// it's made public for `class development` usage only.
191+
//
192+
//
193+
// Supply the the whole `query` string, and placing '?' within, with the same number of arguments in an array.
194+
// It will then determine arguments type, execute, and return results.
187195
query_prepared(string $query_string, array $param_array);
188-
// Will need to call to get last successful query result, will return an object array
196+
// You will need to call this method to get last successful query result.
197+
// It wll return an object array.
189198
queryResult();
190199
```
191200

@@ -203,13 +212,13 @@ $db->insert('profile', $values);
203212
$db->insert('profile', ['name' => 'john john', 'email' => 'john@email', 'phone' => 123456]);
204213

205214
// returns result set given the table name, column fields, and ...conditions
206-
$result = $db->selecting('profile', 'phone', eq('email', $email), between('id', 1, $values));
215+
$result = $db->select('profile', 'phone', eq('email', $email), between('id', 1, $values));
207216

208217
foreach ($result as $row) {
209218
echo $row->phone;
210219
}
211220

212-
$result = $db->selecting('profile', 'name, email',
221+
$result = $db->select('profile', 'name, email',
213222
// Conditionals can also be called, stacked with other functions like:
214223
// innerJoin(), leftJoin(), rightJoin(), fullJoin()
215224
// as (leftTable, rightTable, leftColumn, rightColumn, tableAs, equal condition),
@@ -245,6 +254,83 @@ foreach ($result as $row) {
245254
}
246255
```
247256

257+
Most of shortcut methods have counter **global** _functions_ available.
258+
They can only be access by beginning your `.php` file like:
259+
260+
```php
261+
use function ezsql\functions\functionBelow;
262+
// Or as here, a complete list.
263+
use function ezsql\functions\{
264+
database,
265+
mysqlInstance,
266+
pgsqlInstance,
267+
mssqlInstance,
268+
sqliteInstance,
269+
pdoInstance,
270+
tagInstance,
271+
setInstance,
272+
getInstance,
273+
clearInstance,
274+
///
275+
getVendor,
276+
to_string,
277+
cleanInput,
278+
createCertificate,
279+
///
280+
column,
281+
primary,
282+
foreign,
283+
unique,
284+
index,
285+
addColumn,
286+
dropColumn,
287+
///
288+
eq,
289+
neq,
290+
ne,
291+
lt,
292+
lte,
293+
gt,
294+
gte,
295+
isNull,
296+
isNotNull,
297+
like,
298+
in,
299+
notLike,
300+
notIn,
301+
between,
302+
notBetween,
303+
///
304+
select_into,
305+
insert_select,
306+
create_select,
307+
where,
308+
grouping,
309+
groupBy,
310+
having,
311+
orderBy,
312+
limit,
313+
innerJoin,
314+
leftJoin,
315+
rightJoin,
316+
fullJoin,
317+
union,
318+
unionAll,
319+
///
320+
creating,
321+
deleting,
322+
dropping,
323+
replacing,
324+
selecting,
325+
inserting,
326+
table_setup,
327+
set_table,
328+
set_prefix
329+
};
330+
```
331+
332+
For the functions **usage/docs** see [ezFunctions.php](https://github.com/ezSQL/ezsql/blob/v5/lib/ezFunctions.php).
333+
248334
## For Authors and **[Contributors](https://github.com/ezSQL/ezsql/blob/master/CONTRIBUTORS.md)**
249335

250336
## Contributing

‎lib/ezQueryInterface.php‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<?php
22

3+
namespace ezsql;
4+
35
/**
46
* Author: Lawrence Stubbs <[email protected]>
57
*
@@ -23,11 +25,8 @@
2325
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2426
*
2527
* This software consists of voluntary contributions made by many individuals
26-
* and is licensed under the MIT license.
28+
* and is licensed under the **MIT** license.
2729
*/
28-
29-
namespace ezsql;
30-
3130
interface ezQueryInterface
3231
{
3332
/**
@@ -403,6 +402,23 @@ public function select(string $table = null, $columnFields = '*', ...$conditions
403402
* This method **expects** either `tableSetup(name, prefix)`, `setTable(name)`, or `setPrefix(append)`
404403
* to have been called **before usage**, otherwise will return `false`, if no `table name` previous stored.
405404
*
405+
* Returns an `SQL string` or `result` set, given the
406+
* - column fields, conditions or conditional array.
407+
*
408+
* In the following format:
409+
* ```php
410+
* selecting(
411+
* columns,
412+
* innerJoin() | leftJoin() | rightJoin() | fullJoin(), // alias of joining(inner|left|right|full, leftTable, rightTable, leftColumn, rightColumn, equal condition),
413+
* where( eq( columns, values, _AND ), like( columns, _d ) ),
414+
* groupBy( columns ),
415+
* having( between( columns, values1, values2 ) ),
416+
* orderBy( columns, desc ),
417+
* limit( numberOfRecords, offset ),
418+
* union(table, columnFields, conditions), // Returns an select SQL string with `UNION`
419+
* unionAll(table, columnFields, conditions) // Returns an select SQL string with `UNION ALL`
420+
*);
421+
* ```
406422
* @param mixed $columns fields, string or array
407423
* @param mixed ...$conditions - of the following parameters:
408424
*
@@ -420,12 +436,21 @@ public function select(string $table = null, $columnFields = '*', ...$conditions
420436
*/
421437
public function selecting($columns = '*', ...$conditions);
422438

439+
/**
440+
* Does an `insert` query with an array
441+
* @param $table, - database table to access
442+
* @param $keyValue - table fields, assoc array with key = value (doesn't need escaped)
443+
* @return mixed bool/id of inserted record, or false for error
444+
*/
445+
public function insert(string $table = null, $keyValue);
446+
423447
/**
424448
* Preforms a `insert` method call on a already preset `table name`, and optional `prefix`
425449
*
426450
* This method **expects** either `tableSetup(name, prefix)`, `setTable(name)`, or `setPrefix(append)`
427451
* to have been called **before usage**, otherwise will return `false`, if no `table name` previous stored.
428452
*
453+
* Does an `insert` query with an array
429454
* @param array $keyValue - table fields, assoc array with key = value (doesn't need escaped)
430455
* @return int|bool bool/id of inserted record, or false for error
431456
*/
@@ -622,14 +647,6 @@ public function replace(string $table = null, $keyValue);
622647
*/
623648
function replacing(array $keyValue);
624649

625-
/**
626-
* Does an `insert` query with an array
627-
* @param $table, - database table to access
628-
* @param $keyValue - table fields, assoc array with key = value (doesn't need escaped)
629-
* @return mixed bool/id of inserted record, or false for error
630-
*/
631-
public function insert(string $table = null, $keyValue);
632-
633650
/**
634651
* Does an `insert into select` statement by calling insert method helper then `select` method
635652
* @param $toTable, - database table to insert table into

‎lib/ezsqlModel.php‎

Lines changed: 68 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -7,78 +7,77 @@
77
use function ezsql\functions\getVendor;
88

99
/**
10-
* Core class containing common functions to manipulate query result
11-
* sets once returned
10+
* Core class containing common functions to manipulate **query** `result sets` once returned.
1211
*
13-
* @method set/get{property} - a property that needs to be accessed
12+
* The class properties can be accessed with either a `set` or `get` prefix as a function.
1413
*
15-
* @method void setDebugAll($args);
16-
* @method void setTrace($args);
17-
* @method void setDebugCalled($args);
18-
* @method void setVarDumpCalled($args);
19-
* @method void setShowErrors($args);
20-
* @method void setNumQueries($args);
21-
* @method void setConnQueries($args);
22-
* @method void setCapturedErrors($args);
23-
* @method void setCacheDir($args);
24-
* @method void setUseDiskCache($args);
25-
* @method void setCacheTimeout($args);
26-
* @method void setCacheQueries($args);
27-
* @method void setCacheInserts($args);
28-
* @method void setNumRows($args);
29-
* @method void setDbConnectTime($args);
30-
* @method void setSqlLogFile($args);
31-
* @method void setProfileTimes($args);
32-
* @method void setInsertId($args);
33-
* @method void setLastQuery($args);
34-
* @method void setLastError($args);
35-
* @method void setColInfo($args);
36-
* @method void setTimers($args);
37-
* @method void setTotalQueryTime($args);
38-
* @method void setTraceLog($args);
39-
* @method void setUseTraceLog($args);
40-
* @method void setDoProfile($args);
41-
* @method void setLastResult($args);
42-
* @method void setFromDiskCache($args);
43-
* @method void setDebugEchoIsOn($args);
44-
* @method void setFuncCall($args);
45-
* @method void setAllFuncCalls($args);
46-
* @method void setTable($name);
47-
* @method void setPrefix($append);
14+
* @method void setDebugAll($args)
15+
* @method void setTrace($args)
16+
* @method void setDebugCalled($args)
17+
* @method void setVarDumpCalled($args)
18+
* @method void setShowErrors($args)
19+
* @method void setNumQueries($args)
20+
* @method void setConnQueries($args)
21+
* @method void setCapturedErrors($args)
22+
* @method void setCacheDir($args)
23+
* @method void setUseDiskCache($args)
24+
* @method void setCacheTimeout($args)
25+
* @method void setCacheQueries($args)
26+
* @method void setCacheInserts($args)
27+
* @method void setNumRows($args)
28+
* @method void setDbConnectTime($args)
29+
* @method void setSqlLogFile($args)
30+
* @method void setProfileTimes($args)
31+
* @method void setInsertId($args)
32+
* @method void setLastQuery($args)
33+
* @method void setLastError($args)
34+
* @method void setColInfo($args)
35+
* @method void setTimers($args)
36+
* @method void setTotalQueryTime($args)
37+
* @method void setTraceLog($args)
38+
* @method void setUseTraceLog($args)
39+
* @method void setDoProfile($args)
40+
* @method void setLastResult($args)
41+
* @method void setFromDiskCache($args)
42+
* @method void setDebugEchoIsOn($args)
43+
* @method void setFuncCall($args)
44+
* @method void setAllFuncCalls($args)
45+
* @method void setTable($name)
46+
* @method void setPrefix($append)
4847
*
49-
* @method string getDebugAll();
50-
* @method string getTrace();
51-
* @method string getDebugCalled();
52-
* @method string getVarDumpCalled();
53-
* @method string getShowErrors();
54-
* @method string getNumQueries();
55-
* @method string getConnQueries();
56-
* @method string getCapturedErrors();
57-
* @method string getCacheDir();
58-
* @method string getUseDiskCache();
59-
* @method string getCacheTimeout();
60-
* @method string getCacheQueries();
61-
* @method string getCacheInserts();
62-
* @method string getNumRows();
63-
* @method string getDbConnectTime();
64-
* @method string getSqlLogFile();
65-
* @method string getProfileTimes();
66-
* @method string getInsertId();
67-
* @method string getLastQuery();
68-
* @method string getLastError();
69-
* @method string getColInfo();
70-
* @method string getTimers();
71-
* @method string getTotalQueryTime();
72-
* @method string getTraceLog();
73-
* @method string getUseTraceLog();
74-
* @method string getDoProfile();
75-
* @method string getLastResult();
76-
* @method string getFromDiskCache();
77-
* @method string getDebugEchoIsOn();
78-
* @method string getFuncCall();
79-
* @method string getAllFuncCalls();
80-
* @method string getTable();
81-
* @method string getPrefix();
48+
* @method string getDebugAll()
49+
* @method string getTrace()
50+
* @method string getDebugCalled()
51+
* @method string getVarDumpCalled()
52+
* @method string getShowErrors()
53+
* @method string getNumQueries()
54+
* @method string getConnQueries()
55+
* @method string getCapturedErrors()
56+
* @method string getCacheDir()
57+
* @method string getUseDiskCache()
58+
* @method string getCacheTimeout()
59+
* @method string getCacheQueries()
60+
* @method string getCacheInserts()
61+
* @method string getNumRows()
62+
* @method string getDbConnectTime()
63+
* @method string getSqlLogFile()
64+
* @method string getProfileTimes()
65+
* @method string getInsertId()
66+
* @method string getLastQuery()
67+
* @method string getLastError()
68+
* @method string getColInfo()
69+
* @method string getTimers()
70+
* @method string getTotalQueryTime()
71+
* @method string getTraceLog()
72+
* @method string getUseTraceLog()
73+
* @method string getDoProfile()
74+
* @method string getLastResult()
75+
* @method string getFromDiskCache()
76+
* @method string getDebugEchoIsOn()
77+
* @method string getFuncCall()
78+
* @method string getAllFuncCalls()
79+
* @method string getTable()
80+
* @method string getPrefix()
8281
*/
8382
class ezsqlModel extends ezQuery implements ezsqlModelInterface
8483
{

0 commit comments

Comments
 (0)