Skip to content

Commit c2ab2dc

Browse files
na2axlna2axl
committed
Add README.md file
1 parent 6e7e4b4 commit c2ab2dc

File tree

1 file changed

+286
-0
lines changed

1 file changed

+286
-0
lines changed

‎README.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# JSONDB
2+
Manage local databases with JSON files and JSONDB Query Language (JQL)
3+
4+
## What's that ?
5+
JSONDB is a database manager using JSON files and a custom query
6+
language named **JQL** (**J**SONDB **Q**uery **L**anguage).
7+
8+
## Features
9+
* Database management with servers, databases and tables
10+
* Secure connections to servers with username and password
11+
* Easy custom query language
12+
* Object oriented, with a PDO-like syntax
13+
* Supported JQL queries:
14+
* select()
15+
* insert()
16+
* replace()
17+
* delete()
18+
* update()
19+
* truncate()
20+
* count()
21+
22+
## Getting Started
23+
_Full API and documentation will be soon available on the JSONDB website..._
24+
25+
### Install using composer
26+
JSONDB can be installed through composer:
27+
```sh
28+
$ composer require na2axl/jsondb
29+
```
30+
31+
### Instantiate JSONDB
32+
All JSONDB classes are in the namespace JSONDB. So, you have to
33+
instantiate the class with:
34+
```php
35+
try {
36+
$jsondb = new \JSONDB\JSONDB();
37+
}
38+
catch (\JSONDB\Exception $e) {
39+
echo $e->getMessage();
40+
}
41+
```
42+
43+
### Create a server
44+
If you don't have created a server yet, then:
45+
```php
46+
if (!file_exists($server_path)) {
47+
$jsondb->createServer($server_path, $username, $password);
48+
}
49+
```
50+
It's useful to check if the destination folder doesn't exist before create a server
51+
to avoid errors.
52+
53+
### Connect to a server
54+
Once instantiated, you have to connect to a server before send queries.
55+
```php
56+
$db = $jsondb->connect($server_path, $username, $password, $database_name);
57+
```
58+
* The `$server_path` is the path to the folder which represents a server
59+
(a folder which contains databases)
60+
* The `$username` and the `$password` are the information used to connect
61+
to the database. These information are the same used when creating the server
62+
* The `$database_name` is the name of the database to use with current connection.
63+
This parameter is optional and can be set manually later.
64+
65+
### Create a database
66+
After connection to a server, you can create a database:
67+
```php
68+
$db->createDatabase($database_name);
69+
```
70+
71+
### Use a database
72+
The database to use can be set using the `JSONDB::connect()` method, or manually
73+
using `JSONDB::setDatabase()` method after a connection to a database:
74+
```php
75+
$db->setDatabase($database_name);
76+
```
77+
78+
### Create a table
79+
Once JSONDB is properly connected to a server and use a database, you can create
80+
a table in this database:
81+
```php
82+
$db->createTable($table_name, $prototype);
83+
```
84+
The `$prototype` is an array of `$column_name` => `$column_propeties` pairs.
85+
86+
#### Column properties
87+
There is a list of currently supported column properties:
88+
* `type`: Defines the type of values that the column accepts. Supported types are:
89+
* `int`, `integer`, `number`
90+
* `decimal`, `float`
91+
* `string`
92+
* `char`
93+
* `bool`, `boolean`
94+
* `array`
95+
* `default`: Sets the default value of column
96+
* `max_length`: Used by some type:
97+
* When used with `float`, the number of decimals is reduced to his value
98+
* When used with `string`, the number of characters is reduced to his value
99+
(starting with the first character)
100+
* `auto_increment`: Defines if a column will be an auto incremented column. When
101+
used, the column is automatically set to UNIQUE KEY
102+
* `primary_key`: Defines if a column is a PRIMARY KEY
103+
* `unique_key`: Defines if a column is an UNIQUE KEY
104+
105+
### Send a query
106+
JSONDB can send both direct and prepared queries.
107+
108+
#### Direct queries
109+
```php
110+
$rexults = $db->query($my_query_string);
111+
112+
//// Specially for select() queries
113+
// You can change the fecth mode
114+
$results->setFetchMode(\JSONDB\JSONDB::FETCH_ARRAY);
115+
// or...
116+
$results->setFetchMode(\JSONDB\JSONDB::FETCH_OBJECT);
117+
// Explore results using a while loop
118+
while ($result = $results->fetch()) {
119+
// Do stuff...
120+
}
121+
// Explore results using a foreach loop
122+
forach ($results as $result) {
123+
// Do stuff...
124+
}
125+
```
126+
127+
#### Prepared queries
128+
```php
129+
$query = $db->prepare($my_prepared_query);
130+
$query->bindValue(':key1', $val, \JSONDB\JSONDB::PARAM_INT);
131+
$query->bindValue(':key1', $val, \JSONDB\JSONDB::PARAM_STRING);
132+
$query->bindValue(':key1', $val, \JSONDB\JSONDB::PARAM_BOOL);
133+
$query->bindValue(':key1', $val, \JSONDB\JSONDB::PARAM_NULL);
134+
$results = $query->execute();
135+
136+
//// Specially for select() queries
137+
// You can change the fecth mode
138+
$results->setFetchMode(\JSONDB\JSONDB::FETCH_ARRAY);
139+
// or...
140+
$results->setFetchMode(\JSONDB\JSONDB::FETCH_OBJECT);
141+
// Explore results using a while loop
142+
while ($result = $results->fetch()) {
143+
// Do stuff...
144+
}
145+
// Explore results using a foreach loop
146+
forach ($results as $result) {
147+
// Do stuff...
148+
}
149+
```
150+
151+
### JQL (JSONDB Query Language)
152+
The JQL is the query language used in JSONDB. It's a very easy language based on _extensions_.
153+
A JQL query is in this form:
154+
```php
155+
$db->query('table_name.query(parameters,...).extension1().extension2()...');
156+
```
157+
158+
#### Query Examples
159+
160+
##### select()
161+
Select all from table `users` where `pseudo` = `$id` and `password` = `$pass` or where `mail` = `$id` and `password` = `$pass`
162+
```php
163+
$id = \JSONDB\JSONDB::quote($form_id);
164+
$pass = \JSONDB\JSONDB::quote($form_password);
165+
$db->query("users.select(*).where(pseudo={$id},password={$pass}).where(mail={$id},password={$pass});
166+
```
167+
168+
Select `pseudo` and `mail` from table `users` where `activated` = `true`, order the results by `pseudo` with `desc`endant method, limit the results to the `10` users after the `5`th.
169+
```php
170+
$db->query("users.select(pseudo,mail).where(activated=true).order(pseudo,desc).limit(5,10);
171+
```
172+
173+
##### insert()
174+
Insert a new user in table `users`
175+
```php
176+
$pseudo = \JSONDB\JSONDB::quote($form_pseudo);
177+
$pass = \JSONDB\JSONDB::quote($form_password);
178+
$mail = \JSONDB\JSONDB::quote($form_mail);
179+
$db->query("users.insert({$pseudo},{$pass},{$mail}).in(pseudo,password,mail);
180+
```
181+
Multiple insertion...
182+
```php
183+
$db->query("users.insert({$pseudo1},{$pass1},{$mail1}).and({$pseudo2},{$pass2},{$mail2}).and({$pseudo3},{$pass3},{$mail3}).in(pseudo,password,mail);
184+
```
185+
186+
##### replace()
187+
Replace information of the first user
188+
```php
189+
$db->query("users.replace({$pseudo},{$pass},{$mail}).in(pseudo,password,mail);
190+
```
191+
Multiple replacement...
192+
```php
193+
$db->query("users.replace({$pseudo1},{$pass1},{$mail1}).and({$pseudo2},{$pass2},{$mail2}).and({$pseudo3},{$pass3},{$mail3}).in(pseudo,password,mail);
194+
```
195+
196+
##### delete()
197+
Delete all users
198+
```php
199+
$db->query("users.delete()");
200+
```
201+
Delete all banished users
202+
```php
203+
$db->query("users.delete().where(banished = true)");
204+
```
205+
Delete a specific user
206+
```php
207+
$db->query("users.delete().where(pseudo = {$pseudo}, mail = {$mail})");
208+
```
209+
210+
##### update()
211+
Activate all users
212+
```php
213+
$db->query("users.update(activated).with(true)");
214+
```
215+
Update my information ;-)
216+
```php
217+
$db->query("users.update(mail, password, activated, banished).with({$mail}, {$pseudo}, true, false).where(pseudo = 'na2axl')");
218+
```
219+
220+
##### truncate()
221+
Reset the table `users`
222+
```php
223+
$db->query("users.truncate()");
224+
```
225+
226+
##### count()
227+
Count all banished users
228+
```php
229+
$db->query("users.count(*).as(banished_nb).where(banished = true)");
230+
```
231+
Count all users and group by `activated`
232+
```php
233+
$db->query("users.count(*).as(users_nb).group(activated)");
234+
```
235+
236+
## Full example
237+
```php
238+
try {
239+
$jsondb = \JSONDB\JSONDB();
240+
241+
if (!file_exists('./test') {
242+
$jsondb->createServer('./test', 'root', '');
243+
}
244+
245+
$db = $jsondb->connect('./test', 'root', '')
246+
->createDatabase('test_database')
247+
->setDatabase('test_database'); // Yes, is chainable ! ;-)
248+
249+
$db->createTable('users', array('id' => array('type' => 'int', 'auto_increment' => TRUE),
250+
'name' => array('type' => 'string', 'max_length' => 30, 'not_null' => TRUE),
251+
'surname' => array('type' => 'string', 'max_length' => 30, 'not_null' => TRUE),
252+
'pseudo' => array('type' => 'string', 'max_length' => 15, 'unique_key' => TRUE),
253+
'mail' => array('type' => 'string', 'unique_key' => TRUE),
254+
'password' => array('type' => 'string', 'not_null' => TRUE),
255+
'website' => array('type' => 'string'),
256+
'activated' => array('type' => 'bool', default => false),
257+
'banished' => array('type' => 'bool', default => false)));
258+
259+
// A prepared query
260+
$query = $db->prepare('users.insert(:name, :sname, :pseudo, :mail, :pass).in(name, surname, pseudo, mail, pass)');
261+
$query->bindValue(':name', 'Nana', \JSONDB\JSONDB::PARAM_STRING);
262+
$query->bindValue(':sname', 'Axel', \JSONDB\JSONDB::PARAM_STRING);
263+
$query->bindValue(':pseudo', 'na2axl', \JSONDB\JSONDB::PARAM_STRING);
264+
$query->bindValue(':mail', '[email protected]', \JSONDB\JSONDB::PARAM_STRING);
265+
$query->bindValue(':pass', $password, \JSONDB\JSONDB::PARAM_STRING);
266+
$query->execute();
267+
268+
// After some insertions...
269+
270+
// Select all users
271+
$results = $db->query("users.select(id, name, surname, pseudo)");
272+
// Fetch as object
273+
while ($result = $results->fetch(\JSONDB\JSONDB::FETCH_OBJECT)) {
274+
echo "The user with id: {$result->id} has the name: {$result->name} {$result->surname} and the pseudo: {$result->pseudo}.\n";
275+
}
276+
}
277+
catch (\JSONDB\Exception $e) {
278+
echo $e->getMessage();
279+
}
280+
```
281+
282+
## Authors
283+
* **Axel Nana**: <[email protected]> - [https://tutorialcenters.tk](https://tutorialcenters.tk)
284+
285+
## Copyright
286+
(c) 2016 Centers Technologies. Licensed under MIT ([read license](https://github.com/na2axl/jsondb-php/blob/master/LICENSE)).

0 commit comments

Comments
 (0)