Skip to content

Commit cf4e49f

Browse files
jr-colognejr-cologne
authored
Merge pull request #1 from jr-cologne/jr-cologne_update-readme
Update README.md
2 parents 01aadeb + 68ad2de commit cf4e49f

File tree

1 file changed

+380
-2
lines changed

1 file changed

+380
-2
lines changed

‎README.md‎

Lines changed: 380 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,382 @@
11
# db-class
2-
A simple database class with php and pdo.
2+
This project is a simple database class with php and pdo.
33

4-
More information coming soon!
4+
## Table of Contents
5+
1. [Installation/Setup](#installationsetup)
6+
2. [Basic Usage](#basic-usage)
7+
1. [Require Database Class](#require-database-class)
8+
2. [Instantiate Class / Connect to Database (`__construct()`)](#instantiate-class--connect-to-database-__construct)
9+
3. [Check Connection to Database (`connected()`)](#check-connection-to-database-connected)
10+
4. [Select/Get Data from Database (`select()`)](#selectget-data-from-database-select)
11+
5. [Insert Data into Database (`insert()`)](#insert-data-into-database-insert)
12+
6. [Delete Data/Rows from Database (`delete()`)](#delete-datarows-from-database-delete)
13+
7. [Update Data in Database (`update()`)](#update-data-in-database-update)
14+
8. [Configure Error Handling (`initErrorHandler()`)](#configure-error-handling-initerrorhandler)
15+
9. [Check for Errors (`error()`)](#check-for-errors-error)
16+
10. [Get Errors (`getError()`)](#get-errors-geterror)
17+
3. [Further Examples / Stuff for Testing](#further-examples--stuff-for-testing)
18+
4. [Contributing](#further-examples--stuff-for-testing)
19+
5. [Versioning](#versioning)
20+
6. [License](#license)
21+
22+
## Installation/Setup
23+
If you want to use the database class for your own project, you can simply follow these instructions:
24+
25+
1. Download the ZIP file of this project
26+
2. Unzip it and save the file `DB.php` to your own project directory.
27+
3. If all requirements, like PHP, PDO and a database that fits to that setup, are fulfilled, you should now be ready to start!
28+
29+
## Basic Usage
30+
If you have successfully "installed" everything, you can use the class like that:
31+
32+
### Require Database Class
33+
```php
34+
require_once('your_path/DB.php');
35+
```
36+
37+
### Instantiate Class / Connect to Database (`__construct()`)
38+
To be able to use the class and connect to the database, you have to instantiate it.
39+
40+
To do that, follow that format:
41+
42+
```php
43+
new DB(
44+
string $dbname,
45+
string $user,
46+
string $password,
47+
string $db_type='mysql',
48+
string $host='localhost',
49+
int $pdo_err_mode=PDO::ERRMODE_EXCEPTION
50+
)
51+
```
52+
53+
It's providing these options:
54+
55+
#### Database Name (`$dbname`)
56+
The name of your database you want to connect with. (required)
57+
58+
#### Database User (`$user`)
59+
The user of the database that should interact with it. (required)
60+
61+
#### Password of the Database User (`$password`)
62+
The password of the database user you are using to interact with the database. (required)
63+
64+
#### Database Type (`$db_type`)
65+
The type of the database you are using. (optional)
66+
67+
Default: `mysql`
68+
69+
#### Host (`$host`)
70+
The host of your database. (optional)
71+
72+
Default: `localhost`
73+
74+
#### PDO Error Mode (`$pdo_err_mode`)
75+
The [error mode of pdo](http://php.net/manual/en/pdo.error-handling.php) you want to use. (optional)
76+
77+
Default: `PDO::ERRMODE_EXCEPTION`
78+
79+
Simple example for instantiating the class:
80+
```php
81+
$db = new DB('db-class-example', 'root', '');
82+
```
83+
84+
### Check Connection to Database (`connected()`)
85+
The method `connected()` gives you the ability to check if the connection to the database was established successfully.
86+
87+
The method requires no arguments at all, so you can just call it and then it will give you a return value of `true` or `false` based on the fact if the connection was established or not.
88+
89+
Example:
90+
```php
91+
if ($db->connected()) {
92+
echo 'Successfully connected!';
93+
} else {
94+
echo 'Connection failed';
95+
}
96+
```
97+
98+
### Select/Get Data from Database (`select()`)
99+
In order to get data from the database you can use the method `select()` in the following format:
100+
101+
```php
102+
select(string $sql, array $where=null, int $fetch_mode=PDO::FETCH_ASSOC)
103+
```
104+
105+
The following arguments exist:
106+
107+
#### SQL Query (`$sql`)
108+
The sql to perform the query to the database. (required)
109+
110+
For example:
111+
112+
```sql
113+
SELECT * FROM `users` WHERE `username` = :username
114+
```
115+
116+
#### Values for Where Clause (`$where`)
117+
An array of the values to use in the where clause. (optional)
118+
119+
Default: `null`
120+
121+
Example:
122+
```php
123+
[ 'username' => 'Jack' ]
124+
```
125+
126+
Please note that you have to provide an associative array with keys that match to the placeholders in the sql query, unless you are not using the named placeholders in the query. In case you are just using the question marks as the placeholder, you can get rid of the keys.
127+
128+
#### PDO Fetch Mode (`$fetch_mode`)
129+
The [pdo fetch mode](http://php.net/manual/en/pdostatement.fetch.php). Defines in which format the data is returned from the database. (optional)
130+
131+
Default: `PDO::FETCH_ASSOC`
132+
133+
Example:
134+
135+
```php
136+
PDO::FETCH_NUM
137+
```
138+
139+
An simple example for using everything together:
140+
141+
```php
142+
$data = $db->select("SELECT * FROM `users` WHERE `username` = :username", [ 'username' => 'Jack' ], PDO::FETCH_NUM);
143+
```
144+
145+
### Insert Data into Database (`insert()`)
146+
To insert any data into your database, you can use the `insert()` method with the following format:
147+
148+
```php
149+
insert(string $sql, array $values)
150+
```
151+
152+
The following arguments are required when calling the method:
153+
154+
#### SQL Query (`$sql`)
155+
The sql query to insert the data into your database. (required)
156+
157+
For example that could be:
158+
159+
```sql
160+
INSERT INTO `users` (`username`, `password`) VALUES (:username, :password)
161+
```
162+
163+
#### Values to Insert (`$values`)
164+
An array of the values to be inserted into the database. (required)
165+
166+
Example:
167+
168+
```php
169+
[
170+
'username' => 'test',
171+
'password' => 'hello'
172+
]
173+
```
174+
175+
Please note that you have to provide an associative array with keys that match to the placeholders in the sql query, unless you are not using the named placeholders in the query. In case you are just using the question marks as the placeholder, you can get rid of the keys.
176+
177+
Finally, here is an example for using the `insert()` method to insert data into your database:
178+
179+
```php
180+
$inserted = $db->insert(
181+
"INSERT INTO `users` (`username`, `password`) VALUES (:username, :password)",
182+
[
183+
'username' => 'test',
184+
'password' => 'hello'
185+
]
186+
);
187+
```
188+
189+
### Delete Data/Rows from Database (`delete()`)
190+
The method `delete()` provides the ability to delete data from the database.
191+
192+
You have to follow this format:
193+
194+
```php
195+
delete(string $sql, array $where=null)
196+
```
197+
198+
These are the existing arguments:
199+
200+
#### SQL Query (`$sql`)
201+
The sql query to delete the data from the database. (required)
202+
203+
For example:
204+
205+
```sql
206+
DELETE FROM `users` WHERE `id` = :id
207+
```
208+
209+
#### Values for Where Clause (`$where`)
210+
An array of the values to use in the where clause. (optional)
211+
212+
Default: `null`
213+
214+
Example:
215+
216+
```php
217+
[ 'id' => 3 ]
218+
```
219+
220+
Please note that you have to provide an associative array with keys that match to the placeholders in the sql query, unless you are not using the named placeholders in the query. In case you are just using the question marks as the placeholder, you can get rid of the keys.
221+
222+
Simple example for deleting data with this method:
223+
224+
```php
225+
$deleted = $db->delete("DELETE FROM `users` WHERE `id` = :id", [ 'id' => 3 ]);
226+
```
227+
228+
### Update Data in Database (`update()`)
229+
You can update data in your database by the method `update()`, which has this format:
230+
231+
```php
232+
update(string $sql, array $values)
233+
```
234+
235+
That leads to the following arguments:
236+
237+
#### SQL Query (`$sql`)
238+
The sql query to update the data in your database. (required)
239+
240+
Example:
241+
242+
```sql
243+
UPDATE `users` SET `username` = :username WHERE `id` = :id
244+
```
245+
246+
#### New Values and Values for Where Clause (`values`)
247+
An array of the new values to which it should be updated and the values for the where clause. (required)
248+
249+
For example that could be the following:
250+
251+
```php
252+
[
253+
'username' => 'test',
254+
'id' => 3
255+
]
256+
```
257+
258+
Please note that you have to provide an associative array with keys that match to the placeholders in the sql query, unless you are not using the named placeholders in the query. In case you are just using the question marks as the placeholder, you can get rid of the keys.
259+
260+
Example for using everything this method has to offer together:
261+
262+
```php
263+
$updated = $db->update(
264+
"UPDATE `users` SET `username` = :username WHERE `id` = :id",
265+
[
266+
'username' => 'test',
267+
'id' => 3
268+
]
269+
);
270+
```
271+
272+
### Configure Error Handling (`initErrorHandler()`)
273+
274+
If you want to, you can create your own error handling setup before you instantiate the class.
275+
276+
Important to know is that every method returns the array `$error` on failure with some basic information about the error that is occured.
277+
278+
The following options exist:
279+
280+
#### Environment (`$env`)
281+
`production` or `development`/`dev`
282+
283+
Production: return simple error code and the related error message (default)
284+
285+
Development: return simple error code, the related error message and the [`PDOException Object`](http://php.net/manual/en/class.pdoexception.php)
286+
287+
#### Error Types / Error Messages (`$error_types`)
288+
An array of the error messages with the error code as the key.
289+
290+
Default:
291+
```php
292+
[
293+
0 => 'success',
294+
1 => 'Connection to database failed',
295+
2 => 'Selecting/Getting data from database failed',
296+
3 => 'Inserting data into database failed',
297+
4 => 'Deleting data from database failed',
298+
5 => 'Updating data in database failed',
299+
]
300+
```
301+
302+
**Attention**: Do not change the error codes/keys as long as you don't modify the class according to that! When you change the error code of an error and then just use the database class as normal, it will not work as expected!
303+
304+
Besides from that you can freely change the error messages to your own liking.
305+
306+
To change the config of the error handling, you must call the static method `initErrorHandler(array $error_types=[], string $env='production')`, which will basically set your specified configs, **before** you are instantiating the class.
307+
308+
Example:
309+
```php
310+
DB::initErrorHandler(
311+
[
312+
0 => 'success',
313+
1 => 'Sorry, the connection to the database is failed!',
314+
2 => 'Sorry, we are currently not able to receive data from the database!',
315+
3 => 'Sorry, we are currently not able to insert your data to the database!',
316+
4 => 'Sorry, we are currently not able to delete your data from the database!',
317+
5 => 'Sorry, we are currently not able to update your data in the database!',
318+
]
319+
);
320+
```
321+
322+
Always make sure to pass in the whole array, e.g. not just error 2 and 5, because then only error 2 and 5 will exist.
323+
324+
In case you don't want to change the messages, but you would like to switch the environment, you have to pass in an empty array as the first argument like that:
325+
326+
```php
327+
DB::initErrorHandler(
328+
[],
329+
'development'
330+
);
331+
```
332+
333+
### Check for Errors (`error()`)
334+
In case you want to know if an error occured, you can simply call the method `error()` and it will return you `true` or `false` based on the fact whether there is an error or not.
335+
336+
Example for using that:
337+
338+
```php
339+
if ($db->error()) {
340+
echo 'There is an error!';
341+
} else {
342+
echo 'Everything is fine!';
343+
}
344+
```
345+
346+
### Get Errors (`getError()`)
347+
You can get the array `$error`, which contains all errors, by calling this method.
348+
349+
If there are no errors, it will just return `null`.
350+
351+
Example for getting the whole array:
352+
353+
```php
354+
$error = $db->getError();
355+
```
356+
357+
Example for displaying the error message:
358+
359+
```php
360+
echo $db->getError()['msg'];
361+
```
362+
363+
## Further Examples / Stuff for Testing
364+
You want to see further examples for using the database class or you just want to play around with it a little bit?
365+
366+
- You can find a further examples in the file [`example.php`](https://github.com/jr-cologne/db-class/blob/master/example.php).
367+
- To play around with the database class, you can use the database provided in the file [`db-class-example.sql`](https://github.com/jr-cologne/db-class/blob/master/db-class-example.sql). Just import that in your database client and you are ready to start!
368+
369+
## Contributing
370+
Feel free to contribute to this project! It would be awesome for me if somebody contributes to it.
371+
372+
So don't be shy and start coding! If you want to make sure that I like your idea, you can contact me by a Issue.
373+
374+
But if you decide to contribute to this project, keep in mind that finally it is my choice to merge your Pull Request or not, so also be prepared for a negative decision.
375+
376+
## Versioning
377+
I try to follow the rules of Semantic Versioning as good as I can.
378+
379+
For more information about it and if you want to check out the rules, visit http://semver.org/.
380+
381+
## License
382+
This project is licensed under the [MIT License](https://github.com/jr-cologne/db-class/blob/master/LICENSE).

0 commit comments

Comments
 (0)