Skip to content

Commit f7928b1

Browse files
jr-colognejr-cologne
authored
Update README.md
1 parent b40b24b commit f7928b1

File tree

1 file changed

+197
-12
lines changed

1 file changed

+197
-12
lines changed

‎README.md‎

Lines changed: 197 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,37 +16,44 @@ If you have successfully "installed" everything, you can use the class like that
1616
require_once('your_path/DB.php');
1717
```
1818

19-
### Instantiate Class / Connect to Database
19+
### Instantiate Class / Connect to Database (`__construct`)
2020
To be able to use the class and connect to the database, you have to instantiate it.
2121

2222
To do that, follow that format:
2323

2424
```php
25-
new DB(string $dbname, string $user, string $password, string $db_type='mysql', string $host='localhost', int $pdo_err_mode=PDO::ERRMODE_EXCEPTION)
25+
new DB(
26+
string $dbname,
27+
string $user,
28+
string $password,
29+
string $db_type='mysql',
30+
string $host='localhost',
31+
int $pdo_err_mode=PDO::ERRMODE_EXCEPTION
32+
)
2633
```
2734

2835
It's providing these options:
2936

30-
#### Database Name ('$dbname')
37+
#### Database Name (`$dbname`)
3138
The name of your database you want to connect with. (required)
3239

33-
#### Database User ('$user')
40+
#### Database User (`$user`)
3441
The user of the database that should interact with it. (required)
3542

36-
#### Password of the Database User ('$password')
43+
#### Password of the Database User (`$password`)
3744
The password of the database user you are using to interact with the database. (required)
3845

39-
#### Database Type ('$db_type')
46+
#### Database Type (`$db_type`)
4047
The type of the database you are using. (optional)
4148

4249
Default: `mysql`
4350

44-
#### Host ('$host')
51+
#### Host (`$host`)
4552
The host of your database. (optional)
4653

4754
Default: `localhost`
4855

49-
#### PDO Error Mode ('$pdo_err_mode')
56+
#### PDO Error Mode (`$pdo_err_mode`)
5057
The [error mode of pdo](http://php.net/manual/en/pdo.error-handling.php) you want to use. (optional)
5158

5259
Default: `PDO::ERRMODE_EXCEPTION`
@@ -56,7 +63,7 @@ Simple example for instantiating the class:
5663
$db = new DB('db-class-example', 'root', '');
5764
```
5865

59-
### Check Connection to Database
66+
### Check Connection to Database (`connected()`)
6067
The method `connected()` gives you the ability to check if the connection to the database was established successfully.
6168

6269
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.
@@ -70,7 +77,7 @@ if ($db->connected()) {
7077
}
7178
```
7279

73-
### Select/Get Data from Database
80+
### Select/Get Data from Database (`select()`)
7481
In order to get data from the database you can use the method `select()` in the following format:
7582

7683
```php
@@ -115,7 +122,134 @@ An simple example for using everything together:
115122
$data = $db->select("SELECT * FROM `users`", "WHERE `username` = 'Jack'", PDO::FETCH_NUM);
116123
```
117124

118-
### Configure Error Handling
125+
### Insert Data into Database (`insert()`)
126+
To insert any data into your database, you can use the `insert()` method with the following format:
127+
128+
```php
129+
insert(string $sql, array $values)
130+
```
131+
132+
The following arguments are required when calling the method:
133+
134+
#### SQL Query (`$sql`)
135+
The sql query to insert the data into your database. (required)
136+
137+
For example that could be:
138+
139+
```sql
140+
INSERT INTO `users` (`username`, `password`) VALUES (:username, :password)
141+
```
142+
143+
#### Values to Insert (`$values`)
144+
An array of the values to be inserted into the database. (required)
145+
146+
Example:
147+
148+
```php
149+
[
150+
'username' => 'test',
151+
'password' => 'hello'
152+
]
153+
```
154+
155+
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.
156+
157+
Finally, here is an example for using the `insert()` method to insert data into your database:
158+
159+
```php
160+
$inserted = $db->insert(
161+
"INSERT INTO `users` (`username`, `password`) VALUES (:username, :password)",
162+
[
163+
'username' => 'test',
164+
'password' => 'hello'
165+
]
166+
);
167+
```
168+
169+
### Delete Data/Rows from Database (`delete()`)
170+
The method `delete()` provides the ability to delete data from the database.
171+
172+
You have to follow this format:
173+
174+
```php
175+
delete(string $sql, $where=null)
176+
```
177+
178+
These are the existing arguments:
179+
180+
#### SQL Query (`$sql`)
181+
The sql query to delete the data from the database. (required)
182+
183+
For example:
184+
185+
```sql
186+
DELETE FROM `users` WHERE `id` = :id
187+
```
188+
189+
#### Values for Where Clause (`$where`)
190+
An array of the values to use in the where clause. (optional)
191+
192+
Default: `null`
193+
194+
Example:
195+
196+
```php
197+
[ 'id' => 3 ]
198+
```
199+
200+
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.
201+
202+
Simple example for deleting data with this method:
203+
204+
```php
205+
$deleted = $db->delete("DELETE FROM `users` WHERE `id` = :id", [ 'id' => 3 ]);
206+
```
207+
208+
### Update Data in Database (`update()`)
209+
You can update data in your database by the method `update()`, which has this format:
210+
211+
```php
212+
update(string $sql, $values)
213+
```
214+
215+
That leads to the following arguments:
216+
217+
#### SQL Query (`$sql`)
218+
The sql query to update the data in your database. (required)
219+
220+
Example:
221+
222+
```sql
223+
UPDATE `users` SET `username` = :username WHERE `id` = :id
224+
```
225+
226+
#### New Values and Values for Where Clause (`values`)
227+
An array of the new values to which it should be updated and the values for the where clause. (required)
228+
229+
For example that could be the following:
230+
231+
```php
232+
[
233+
'username' => 'test',
234+
'id' => 3
235+
]
236+
```
237+
238+
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.
239+
240+
Example for using everything this method has to offer together:
241+
242+
```php
243+
$updated = $db->update(
244+
"UPDATE `users` SET `username` = :username WHERE `id` = :id",
245+
[
246+
'username' => 'test',
247+
'id' => 3
248+
]
249+
);
250+
```
251+
252+
### Configure Error Handling (`initErrorHandler()`)
119253

120254
If you want to, you can create your own error handling setup before you instantiate the class.
121255

@@ -130,7 +264,7 @@ Production: return simple error code and the related error message (default)
130264

131265
Development: return simple error code, the related error message and the [`PDOException Object`](http://php.net/manual/en/class.pdoexception.php)
132266

133-
#### Error Types / Error Messages ('$error_types')
267+
#### Error Types / Error Messages (`$error_types`)
134268
An array of the error messages with the error code as the key.
135269

136270
Default:
@@ -175,3 +309,54 @@ DB::initErrorHandler(
175309
'development'
176310
);
177311
```
312+
313+
### Check for Errors (`error()`)
314+
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.
315+
316+
Example for using that:
317+
318+
```php
319+
if ($db->error()) {
320+
echo 'There is an error!';
321+
} else {
322+
echo 'Everything is fine!';
323+
}
324+
```
325+
326+
### Get Errors (`getError()`)
327+
You can get the array `$error`, which contains all errors, by calling this method.
328+
329+
If there are no errors, it will just return `null`.
330+
331+
Example for getting the whole array:
332+
333+
```php
334+
$error = $db->getError();
335+
```
336+
337+
Example for displaying the error message:
338+
339+
```php
340+
echo $db->getError()['msg'];
341+
```
342+
343+
## Further Examples / Stuff for Testing
344+
You want to see further examples for using the database class or you just want to play around with it a little bit?
345+
346+
- You can find a further examples in the file [`example.php`](https://github.com/jr-cologne/db-class/blob/master/example.php).
347+
- 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!
348+
349+
## Contributing
350+
Feel free to contribute to this project! It would be awesome for me if somebody contributes to it.
351+
352+
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.
353+
354+
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.
355+
356+
## Versioning
357+
I try to follow the rules of Semantic Versioning as good as I can.
358+
359+
For more information about it and if you want to check out the rules, visit http://semver.org/.
360+
361+
## License
362+
This project is licensed under the [MIT License](https://github.com/jr-cologne/db-class/blob/master/LICENSE).

0 commit comments

Comments
 (0)