simplon / mysql
Simplon MySQL Library
Installs: 78 476
Dependents: 10
Suggesters: 0
Security: 0
Stars: 70
Watchers: 7
Forks: 22
Open Issues: 8
Requires
- php: >=8.2
- ext-pdo: *
Requires (Dev)
- phpunit/phpunit: ^11.4@dev
- dev-master
- 3.1.0
- 3.0.0
- 2.2.10
- 2.2.9
- 2.2.8
- 2.2.7
- 2.2.6
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.11
- 2.1.10
- 2.1.9
- 2.1.8
- 2.1.7
- 2.1.6
- 2.1.5
- 2.1.4
- 2.1.3
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.2
- 2.0.1
- 2.0.0
- 1.4.3
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.4
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.7.0
- 0.6.0
- 0.5.0
- 0.4.10
- 0.4.8
- 0.4.7
- 0.4.6
- 0.4.5
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.1
- 0.2.0
- 0.1.5
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1.0
- dev-feature/php82
- dev-fix/null-values
- dev-php71
- dev-refactor
- dev-fix/te-non-column-conds
- dev-develop
This package is auto-updated.
Last update: 2024-11-02 10:35:45 UTC
README
_ _ _ ___(_)_ __ ___ _ __ | | ___ _ __ _ __ ___ _ _ ___ __ _| | / __| | '_ ` _ \| '_ \| |/ _ \| '_ \ | '_ ` _ \| | | / __|/ _` | | \__ \ | | | | | | |_) | | (_) | | | | | | | | | | |_| \__ \ (_| | | |___/_|_| |_| |_| .__/|_|\___/|_| |_| |_| |_| |_|\__, |___/\__, |_| |_| |___/ |_|
Simplon/Mysql
- Installing
- Direct vs. CRUD
- Setup connection
- Usage: Direct access
4.1. Query
4.2. Insert
4.3. Update
4.4. Replace
4.5. Delete
4.6. Execute - Usage: CRUD
5.1. Setup store
5.2. Setup model
5.3. Connect to store
5.4. Query
5.5. Insert
5.6. Update
5.7. Delete
5.8. Custom queries - IN() Clause Handling
6.1. The issue
6.2. The solution - Exceptions
Dependecies
- PHP >= 7.1
- PDO
1. Installing
Easy install via composer. Still no idea what composer is? Inform yourself here.
{ "require": { "simplon/mysql": "*" } }
2. Direct vs. CRUD
I implemented two different ways of interacting with MySQL. The first option is the usual one which interacts directly with the database. Following a straight forward example to show you what I mean:
$data = $dbConn->fetchRow('SELECT * FROM names WHERE name = :name', ['name' => 'Peter']); // // $data is an array with our result //
In constrast to the prior method CRUD is more structured with store
and model
. Further, it uses Builder Patterns to interact with the database. A quick example of how we would rewrite the above direct query
:
$store = new NamesStore($dbConn); $model = $store->read( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_NAME, 'Peter') ); // // $model is a class with our result data abstracted //
3. Setup connection
The library requires a config value object in order to instantiate a connection with MySQL. See how it's done:
$pdo = new PDOConnector( 'localhost', // server 'root', // user 'root', // password 'database' // database ); $pdoConn = $pdo->connect('utf8', []); // charset, options // // you could now interact with PDO for instance setting attributes etc: // $pdoConn->setAttribute($attribute, $value); // $dbConn = new Mysql($pdoConn);
4. Usage: Direct access
4.1. Query
FetchColumn
Returns a selected column from the first match. The example below returns id
or null
if nothing was found.
$result = $dbConn->fetchColumn('SELECT id FROM names WHERE name = :name', ['name' => 'Peter']); // result var_dump($result); // '1' || null
FetchColumnMany
Returns an array with the selected column from all matching datasets. In the example below an array with all ids
will be returned or null
if nothing was found.
$result = $dbConn->fetchColumnMany('SELECT id FROM names WHERE name = :name', ['name' => 'Peter']); // result var_dump($result); // ['1', '15', '30', ...] || null
FetchColumnManyCursor
Returns one matching dataset at a time. It is resource efficient and therefore handy when your result has many data. In the example below you either iterate through the foreach loop in case you have matchings or nothing will happen.
$cursor = $dbConn->fetchColumnMany('SELECT id FROM names WHERE name = :name', ['name' => 'Peter']); foreach ($cursor as $result) { var_dump($result); // '1' }
FetchRow
Returns all selected columns from a matched dataset. The example below returns id
, age
for the matched dataset. If nothing got matched null
will be returned.
$result = $dbConn->fetchRow('SELECT id, age FROM names WHERE name = :name', ['name' => 'Peter']); var_dump($result); // ['id' => '1', 'age' => '22'] || null
FetchRowMany
Returns all selected columns from all matched dataset. The example below returns for each matched dataset id
, age
. If nothing got matched null
will be returned.
$result = $dbConn->fetchRowMany('SELECT id, age FROM names WHERE name = :name', ['name' => 'Peter']); var_dump($result); // [ ['id' => '1', 'age' => '22'], ['id' => '15', 'age' => '40'], ... ] || null
FetchRowManyCursor
Same explanation as for FetchColumnManyCursor
except that we receive all selected columns.
$result = $dbConn->fetchRowMany('SELECT id, age FROM names WHERE name = :name', ['name' => 'Peter']); foreach ($cursor as $result) { var_dump($result); // ['id' => '1', 'age' => '22'] }
4.2. Insert
Single data
Inserting data into the database is pretty straight forward. Follow the example below:
$data = [ 'id' => false, 'name' => 'Peter', 'age' => 45, ]; $id = $dbConn->insert('names', $data); var_dump($id); // 50 || bool
The result depends on the table. If the table holds an autoincrementing ID
column you will receive the ID count for the inserted data. If the table does not hold such a field you will receive true
for a successful insert. If anything went bogus you will receive false
.
Many datasets
Follow the example for inserting many datasets at once:
$data = [ [ 'id' => false, 'name' => 'Peter', 'age' => 45, ], [ 'id' => false, 'name' => 'Peter', 'age' => 16, ], ]; $id = $dbConn->insertMany('names', $data); var_dump($id); // 50 || bool
The result depends on the table. If the table holds an autoincrementing ID
column you will receive the ID count for the inserted data. If the table does not hold such a field you will receive true
for a successful insert. If anything went bogus you will receive false
.
4.3. Updating
Simple update statement
Same as for insert statements accounts for updates. Its easy to understand. If the update succeeded the response will be true
. If nothing has been updated you will receive null
.
$conds = [ 'id' => 50, ]; $data = [ 'name' => 'Peter', 'age' => 50, ]; $result = $dbConn->update('names', $conds, $data); var_dump($result); // true || null
Custom update conditions query
Same as for insert statements accounts for updates. Its easy to understand. If the update succeeded the response will be true
. If nothing has been updated you will receive null
.
$conds = [ 'id' => 50, 'name' => 'Peter', ]; // custom conditions query $condsQuery = 'id = :id OR name =: name'; $data = [ 'name' => 'Peter', 'age' => 50, ]; $result = $dbConn->update('names', $conds, $data, $condsQuery); var_dump($result); // true || null
4.4. Replace
As MySQL states it: REPLACE
works exactly like INSERT
, except that if an old row in the table has the same value as a new row for a PRIMARY KEY
or a UNIQUE index
, the old row is deleted before the new row is inserted.
Replace a single datasets
As a result you will either receive the INSERT ID
or false
in case something went wrong.
$data = [ 'id' => 5, 'name' => 'Peter', 'age' => 16, ]; $result = $dbConn->replace('names', $data); var_dump($result); // 1 || false
Replace multiple datasets
As a result you will either receive an array of INSERT IDs
or false
in case something went wrong.
$data = [ [ 'id' => 5, 'name' => 'Peter', 'age' => 16, ], [ 'id' => 10, 'name' => 'John', 'age' => 22, ], ]; $result = $dbConn->replaceMany('names', $data); var_dump($result); // [5, 10] || false
4.5. Delete
Simple delete conditions
The following example demonstrates how to remove data. If the query succeeds we will receive true
else false
.
$result = $dbConn->delete('names', ['id' => 50]); var_dump($result); // true || false
Custom delete conditions query
The following example demonstrates how to remove data with a custom conditions query. If the query succeeds we will receive true
else false
.
$conds = [ 'id' => 50, 'name' => 'John', ]; // custom conditions query $condsQuery = 'id = :id OR name =: name'; $result = $dbConn->delete('names', $conds, $condsQuery); var_dump($result); // true || false
4.6. Execute
This method is ment for calls which do not require any parameters such as TRUNCATE
. If the call succeeds you will receive true
. If it fails an MysqlException
will be thrown.
$result = $dbConn->executeSql('TRUNCATE names'); var_dump($result); // true
5. Usage: CRUD
The following query examples will be a rewrite of the aforementioned direct access
examples. For this we need a Store
and a related Model
.
5.1. Setup store
namespace Test\Crud; use Simplon\Mysql\CreateQueryBuilder;use Simplon\Mysql\CrudModelInterface;use Simplon\Mysql\CrudStore;use Simplon\Mysql\DeleteQueryBuilder;use Simplon\Mysql\MysqlException;use Simplon\Mysql\ReadQueryBuilder;use Simplon\Mysql\UpdateQueryBuilder; /** * @package Test\Crud */ class NamesStore extends CrudStore { /** * @return string */ public function getTableName(): string { return 'names'; } /** * @return CrudModelInterface */ public function getModel(): CrudModelInterface { return new NameModel(); } /** * @param CreateQueryBuilder $builder * * @return NameModel * @throws MysqlException */ public function create(CreateQueryBuilder $builder): NameModel { /** @var NameModel $model */ $model = $this->crudCreate($builder); return $model; } /** * @param ReadQueryBuilder|null $builder * * @return NameModel[]|null * @throws MysqlException */ public function read(?ReadQueryBuilder $builder = null): ?array { /** @var NameModel[]|null $response */ $response = $this->crudRead($builder); return $response; } /** * @param ReadQueryBuilder $builder * * @return null|NameModel * @throws MysqlException */ public function readOne(ReadQueryBuilder $builder): ?NameModel { /** @var NameModel|null $response */ $response = $this->crudReadOne($builder); return $response; } /** * @param UpdateQueryBuilder $builder * * @return NameModel * @throws MysqlException */ public function update(UpdateQueryBuilder $builder): NameModel { /** @var NameModel|null $model */ $model = $this->crudUpdate($builder); return $model; } /** * @param DeleteQueryBuilder $builder * * @return bool * @throws MysqlException */ public function delete(DeleteQueryBuilder $builder): bool { return $this->crudDelete($builder); } /** * @param int $id * * @return null|NameModel * @throws MysqlException */ public function customMethod(int $id): ?NameModel { $query = 'SELECT * FROM ' . $this->getTableName() . ' WHERE id=:id'; if ($result = $this->getCrudManager()->getMysql()->fetchRow($query, ['id' => $id])) { return (new NameModel())->fromArray($result); } return null; } }
5.2. Setup model
<?php namespace Test\Crud; use Simplon\Mysql\CrudModel; /** * @package Test\Crud */ class NameModel extends CrudModel { const COLUMN_ID = 'id'; const COLUMN_NAME = 'name'; const COLUMN_AGE = 'age'; /** * @var int */ protected $id; /** * @var string */ protected $name; /** * @var int */ protected $age; /** * @return int */ public function getId(): int { return (int)$this->id; } /** * @param int $id * * @return NameModel */ public function setId(int $id): NameModel { $this->id = $id; return $this; } /** * @return string */ public function getName(): string { return $this->name; } /** * @param string $name * * @return NameModel */ public function setName(string $name): NameModel { $this->name = $name; return $this; } /** * @return int */ public function getAge(): int { return (int)$this->age; } /** * @param int $age * * @return NameModel */ public function setAge(int $age): NameModel { $this->age = $age; return $this; } }
5.3. Connect to store
In order to interact with our store we need to create an instance. For the following points we will make use of this instance.
$store = new NamesStore($pdoConn);
5.4. Query
Fetch one item
Returns a name model
or NULL
if nothing could be matched.
$model = $store->readOne( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_NAME, 'Peter') ); echo $model->getId(); // prints user id
You can make use of operators from the addCondition
:
$model = $store->readOne( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_AGE, 20, '>') ); echo $model->getId(); // prints user id
Fetch many items
Returns an array of name models
or NULL
if nothing could be matched.
$models = $store->read( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_NAME, 'Peter') ); echo $models[0]->getId(); // prints user id from first matched model
5.5. Insert
The following example shows how to create a new store entry.
$model = $store->create( CreateQueryBuilder::create()->setModel( (new NameModel()) ->setName('Johnny') ->setAge(22) ) );
5.6. Update
The following example shows how to update an existing store entry.
// // fetch a model // $model = $store->readOne( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_NAME, 'Peter') ); // // update age // $model->setAge(36); // // persist change // $model = $store->update( UpdateQueryBuilder::create() ->setModel($model) ->addCondition(NameModel::COLUMN_ID, $model->getId()) );
5.7. Delete
The following example shows how to delete an existing store entry.
// // fetch a model // $model = $store->readOne( ReadQueryBuilder::create()->addCondition(NameModel::COLUMN_NAME, 'Peter') ); // // delete model from store // $store->delete( DeleteQueryBuilder::create() ->addCondition(NameModel::COLUMN_ID, $model->getId()) )
5.8. Custom queries
You also have the possibility to write custom queries/handlings for your store. I added a method to the store which demonstrates on how to implement custom handlings.
/** * @param int $id * * @return null|NameModel * @throws MysqlException */ public function customMethod(int $id): ?NameModel { $query = 'SELECT * FROM ' . $this->getTableName() . ' WHERE id=:id'; if ($result = $this->getCrudManager()->getMysql()->fetchRow($query, ['id' => $id])) { return (new NameModel())->fromArray($result); } return null; }
6. IN() Clause Handling
6.1. The issue
There is no way using an IN()
clause via PDO. This functionality is simply not given. However, you could do something like the following:
$ids = array(1,2,3,4,5); $query = "SELECT * FROM users WHERE id IN (" . join(',', $ids) . ")";
Looks good at first sight - not sexy but probably does the job, right? Wrong. This approach only works with INTEGERS
and it does not ESCAPE
the user's input - the reason why we use PDO
in first place.
Just for the record here is a string example which would not work:
$emails = array('johnny@me.com', 'peter@ibm.com'); $query = "SELECT * FROM users WHERE email IN (" . join(',', $emails) . ")";
The only way how this would work is by wrapping each value like the following: '"email"'
. Way too much work.
6.2. The solution
To take advantage of the built in IN() Clause
with escaping and type handling do the following for the direct access. CRUD will do the query building automatically for you.
// integers $conds = array('ids' => array(1,2,3,4,5)); $query = "SELECT * FROM users WHERE id IN (:ids)"; // strings $conds = array('emails' => array('johnny@me.com', 'peter@ibm.com')); $query = "SELECT * FROM users WHERE email IN (:emails)";
7. Exceptions
For both access methods (direct, sqlmanager) occuring exceptions will be wrapped by a MysqlException
. All essential exception information will be summarised as JSON
within the Exception Message
.
Here is an example of how that might look like:
{"query":"SELECT pro_id FROM names WHERE connector_type = :connectorType","params":{"connectorType":"FB"},"errorInfo":{"sqlStateCode":"42S22","code":1054,"message":"Unknown column 'pro_id' in 'field list'"}}
License
Simplon/Mysql is freely distributable under the terms of the MIT license.
Copyright (c) 2017 Tino Ehrich (tino@bigpun.me)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.