1. Connection - TerminusStudio/ezDB GitHub Wiki
Connections
Connections are at the lowest layer of ezDB. They are used to create and manage connections to multiple databases.
It is completely optional to use the Connections class and you can instantiate a Connection class directly if you only want to use a single connection. The advantage of the Connections class is that it allows you to access a connection anywhere in your code by using a single command.
A connection can then be accessed by using the command below,
$connection = Connections::connection('name')
The connection() method accepts one argument which is the name of the connection. If left empty, default is used.
A connection can be added by using the command below,
Connections::addConnection(new DatabaseConfig($configArray), 'name');
The first argument needs to be an DatabaseConfig object and the second one specifies the name of the connection. If name is unspecified, default will be used as name.
Connection
A Connection class instance manages the connection to a single database. The Connection class can be instantiated directly by only passing a DatabaseConfig instance.
You can pick the driver to use for the connection by specifying it in the $configArray that is passed to the DatabaseConfig. You can use any number of driver in ezDB but each connection can only use one driver.
The connection class only connects to the database when any of it's functions is used. This speeds up your app loading time by not opening a database connection that isn't used at all.
Below is a table containing all of the functions that's available using the Connection class.
| Function | Description |
|---|---|
| connect() | Opens a connection to the database. |
| reset() | Reset the connection. |
| close() | Close the connection. |
| getDriver() | Return the Driver instance. |
| getDriverHandle() | Return the PHP handle for the database connection. |
| getBuilderClass() | Return a string specifying the builder class that needs to be used. |
| isConnected() | Check if a connection is already open. |
| executeRaw($rawSQL) | Execute a raw statement on the database. |
| insert($query, ...$params) | Execute a prepared insert statement on the database. Returns number of affected rows. |
| update($query, ...$params) | Execute a prepared update statement on the database. Returns number of affected rows. |
| select($query, ...$params) | Execute a prepared select statement on the database. Returns an array of objects which has the result. |
| delete($query, ...$params) | Execute a prepared delete statement on the database. Returns number of affected rows. |
More methods can be accessed by using getDriver(). Scroll down to the Drivers section to see all the methods that's available on driver level.
DatabaseConfig Class
This class is used to manage the configuration details for a connection. It accepts an array which should contain the following information,
$configArray = [
'driver' => 'mysqli',
'host' => 'localhost',
'port' => 'port',
'database' => 'database',
'username' => 'user',
'password' => 'pass',
'builder' => 'Builder class'
]
- driver - The PHP driver that needs to be used for connection. Currently supports MySQLi or PDO. To add support for more drivers, take a look at the Drivers Section.
- host - The database hostname
- port - The port for database connection (default: empty)
- database - The database name
- username - Username used for connection
- password - Password used for connection
- builder - Any class that extends from Builder. This overrides which Builder class Model's instantiate. (default: \TS\ezDB\Query\Builder::class)
Driver
All driver classes must extend from DriverInterface. Drivers provide an interface to communicate with database by using the built in PHP extensions. Currently PDO and MySQLi are both supported.
Driver's are instantiated automatically by the Connection class and can be accessed by calling the getDriver() function in the connection class. It is not recommended to instantiate a driver class directly.
| Function Name | Description |
|---|---|
| connect() | Connect to the database. Returns a boolean for connection status. |
| handle() | Returns the PHP handle to the connection. |
| close() | Closes the connection. |
| reset() | Resets the connection. |
| prepare(string $query) | Use this to prepare a SQL statement. It returns a statement object (depending on the driver you use). |
| bind($stmt, &...$params) | Use this function to bind parameters to a statement. It accepts the statement object generated by the previous function and any number of parameters that needs to be binded. |
| execute($stmt, $close = true, $fetch = false) | Execute the prepared statement. Optional parameters include close and fetch. Close is used for closing the statement, and fetch can be used when expecting results from the database. |
| query(string $query) | Execute a raw query. Make sure you escape any user given value before running this. |
| exec(string $sql) | Execute raw SQL. This function enables executing multiple SQL statements at once. (Using this is not recommended, return values depend on the driver you use) |
| escape(string $value) | Escape special characters in string |
| getLastInsertId() | Get the last insert ID. |
| getRowCount() | Get the number of affected rows |
| getProcessor() | Get the processor object which is used to process builder queries. |
If the driver is instantiated directly without a Connection class, it needs to be connected before most of the methods can be accessed. If the connect() function is not called first, a Fatal Error will be thrown by PHP for trying to access a null object. This is why it is recommended to use the Connection class.