diff --git a/README.md b/README.md index dec3cd3..51e48f2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ $db->for(string $table) ->with(array $model) ->where(array $filters) ->order(array $order_by) -->limit(1) +->limit(int|array $limit) ->select(array $columns): array|bool; ``` which would be equivalent to the following in MySQL: @@ -58,6 +58,8 @@ use libmysqldriver\MySQL; $db = new MySQL($host, $user, $pass, $db); ``` +All executor methods [`select()`](#select), [`update()`](#update), and [`insert()`](#insert) will return a [`mysqli_result`](https://www.php.net/manual/en/class.mysqli-result.php) object. + # SELECT Use `MySQL->select()` to retrieve columns from a database table. @@ -67,8 +69,7 @@ Pass an associative array of strings, CSV string, or null to this method to filt ```php $db->select( array|string|null $columns -): array|bool; -// Returns array of arrays for each row, or bool if no columns were defined +): mysqli_result; ``` In most cases you probably want to select with a constraint. Chain the [`where()`](#where) method before `select()` to filter the query @@ -118,7 +119,7 @@ Use `MySQL->insert()` to append a new row to a database table $db->insert( // Array of values to INSERT array $values -): bool +): mysqli_result // Returns true if row was inserted ``` @@ -145,7 +146,7 @@ Modify existing rows with `MySQL->update()` $db->get( // Key, value array of column names and values to update array $fields, -): bool; +): mysqli_result; // Returns true if at least 1 row was changed ``` diff --git a/src/DatabaseDriver.php b/src/DatabaseDriver.php deleted file mode 100644 index b02acdf..0000000 --- a/src/DatabaseDriver.php +++ /dev/null @@ -1,44 +0,0 @@ -execute_query($sql, self::to_list_array($params)); - $res = []; - - // Fetch rows into sequential array - while ($row = $query->fetch_assoc()) { - $res[] = $row; - } - - return $res; - } - - // Execute SQL query with optional prepared statement and return true if query was successful - public function exec_bool(string $sql, mixed $params = null): bool { - $query = $this->execute_query($sql, self::to_list_array($params)); - - return gettype($query) === "boolean" - // Type is already a bool, so return it as is - ? $query - // Return true if rows were matched - : $query->num_rows > 0; - } - } diff --git a/src/MySQL.php b/src/MySQL.php index 2776854..1357218 100644 --- a/src/MySQL.php +++ b/src/MySQL.php @@ -3,14 +3,13 @@ namespace libmysqldriver; use \Exception; - use \victorwesterlund\xEnum; - use libmysqldriver\Driver\DatabaseDriver; - - require_once "DatabaseDriver.php"; + use \mysqli; + use \mysqli_stmt; + use \mysqli_result; // Interface for MySQL_Driver with abstractions for data manipulation - class MySQL extends DatabaseDriver { + class MySQL extends mysqli { private string $table; private ?array $model = null; @@ -25,12 +24,21 @@ parent::__construct(...func_get_args()); } + /* + # Helper methods + */ + private function throw_if_no_table() { if (!$this->table) { throw new Exception("No table name defined"); } } + // Coerce input to single dimensional array + private static function to_list_array(mixed $input): array { + return array_values(is_array($input) ? $input : [$input]); + } + // Return value(s) that exist in $this->model private function in_model(string|array $columns): ?array { // Place string into array @@ -39,7 +47,11 @@ return array_filter($columns, fn($col): string => in_array($col, $this->model)); } - /* ---- */ + /* + # Definers + These methods are used to build an SQL query by chaining methods together. + Defined parameters will then be executed by an Executer method. + */ // Use the following table name public function for(string $table): self { @@ -155,10 +167,13 @@ return $this; } - /* ---- */ + /* + # Executors + These methods execute various statements that each return a mysqli_result + */ // Create Prepared Statament for SELECT with optional WHERE filters - public function select(array|string|null $columns = null): array|bool { + public function select(array|string|null $columns = null): mysqli_result { $this->throw_if_no_table(); // Create array of columns from CSV @@ -184,19 +199,14 @@ // Interpolate components into an SQL SELECT statmenet and execute $sql = "SELECT {$columns_sql} FROM {$this->table}{$filter_sql}{$order_by_sql}{$limit_sql}"; - // No columns were specified, return true if query matched rows - if (!$columns) { - return $this->exec_bool($sql, $this->filter_values); - } - // Return array of matched rows - $exec = $this->exec($sql, $this->filter_values); + $exec = $this->execute_query($sql, self::to_list_array($this->filter_values)); // Return array if exec was successful. Return as flattened array if flag is set return empty($exec) || !$this->flatten ? $exec : $exec[0]; } // Create Prepared Statement for UPDATE using PRIMARY KEY as anchor - public function update(array $entity): bool { + public function update(array $entity): mysqli_result { $this->throw_if_no_table(); // Make constraint for table model if defined @@ -224,11 +234,11 @@ // Interpolate components into an SQL UPDATE statement and execute $sql = "UPDATE {$this->table} SET {$changes} {$filter_sql}"; - return $this->exec_bool($sql, $values); + return $this->execute_query($sql, self::to_list_array($values)); } // Create Prepared Statemt for INSERT - public function insert(array $values): bool { + public function insert(array $values): mysqli_result { $this->throw_if_no_table(); // A value for each column in table model must be provided @@ -241,6 +251,11 @@ // Interpolate components into an SQL INSERT statement and execute $sql = "INSERT INTO {$this->table} VALUES ({$values_stmt})"; - return $this->exec_bool($sql, $values); + return $this->execute_query($sql, self::to_list_array($values)); + } + + // Execute SQL query with optional prepared statement and return mysqli_result + public function exec(string $sql, mixed $params = null): mysqli_result { + return $this->execute_query($sql, self::to_list_array($params)); } }