Skip to content

Commit d3fe1ef

Browse files
author
claudiobizzotto
committed
All the things!
0 parents  commit d3fe1ef

24 files changed

+4726
-0
lines changed

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
vendor/
2+
3+
tests/_output/*
4+
tests/_output/*

‎.php_cs

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?php
2+
3+
$finder = PhpCsFixer\Finder::create()->in(__DIR__);
4+
5+
return PhpCsFixer\Config::create()
6+
->setRules(array(
7+
'@Symfony' => true,
8+
'array_syntax' => ['syntax' => 'short'],
9+
'blank_line_before_return' => false,
10+
'cast_spaces' => false,
11+
'concat_space' => false,
12+
'linebreak_after_opening_tag' => true,
13+
'modernize_types_casting' => true,
14+
'no_empty_comment' => false,
15+
'no_empty_phpdoc' => false,
16+
'no_empty_statement' => false,
17+
'no_multiline_whitespace_before_semicolons' => true,
18+
'no_unneeded_control_parentheses' => false,
19+
'ordered_class_elements' => true,
20+
'ordered_imports' => true,
21+
'phpdoc_align' => false,
22+
'phpdoc_annotation_without_dot' => false,
23+
'pre_increment' => false,
24+
'psr4' => true,
25+
'strict_param' => true,
26+
'trailing_comma_in_multiline_array' => false
27+
))
28+
->setRiskyAllowed(true)
29+
->setFinder($finder)
30+
;

‎.php_cs.cache

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{"php":"5.6.27-0+deb8u1","version":"2.0.0:v2.0.0#f3baf72eb2f58bf275b372540f5b47d25aed910f","rules":{"encoding":true,"full_opening_tag":true,"blank_line_after_namespace":true,"braces":true,"class_definition":{"singleLine":true},"elseif":true,"function_declaration":true,"indentation_type":true,"line_ending":true,"lowercase_constants":true,"lowercase_keywords":true,"method_argument_space":true,"no_closing_tag":true,"no_spaces_after_function_name":true,"no_spaces_inside_parenthesis":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":true,"single_import_per_statement":true,"single_line_after_imports":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"visibility_required":true,"binary_operator_spaces":{"align_double_arrow":false,"align_equals":false},"blank_line_after_opening_tag":true,"declare_equal_normalize":true,"function_typehint_space":true,"hash_to_slash_comment":true,"heredoc_to_nowdoc":true,"include":true,"lowercase_cast":true,"method_separation":true,"native_function_casing":true,"new_with_braces":true,"no_alias_functions":true,"no_blank_lines_after_class_opening":true,"no_blank_lines_after_phpdoc":true,"no_extra_consecutive_blank_lines":["curly_brace_block","extra","parenthesis_brace_block","square_brace_block","throw","use"],"no_leading_import_slash":true,"no_leading_namespace_whitespace":true,"no_mixed_echo_print":{"use":"echo"},"no_multiline_whitespace_around_double_arrow":true,"no_short_bool_cast":true,"no_singleline_whitespace_before_semicolons":true,"no_spaces_around_offset":true,"no_trailing_comma_in_list_call":true,"no_trailing_comma_in_singleline_array":true,"no_unreachable_default_argument_value":true,"no_unused_imports":true,"no_whitespace_before_comma_in_array":true,"no_whitespace_in_blank_line":true,"normalize_index_brace":true,"object_operator_without_whitespace":true,"php_unit_fqcn_annotation":true,"phpdoc_indent":true,"phpdoc_inline_tag":true,"phpdoc_no_access":true,"phpdoc_no_alias_tag":true,"phpdoc_no_empty_return":true,"phpdoc_no_package":true,"phpdoc_scalar":true,"phpdoc_separation":true,"phpdoc_single_line_var_spacing":true,"phpdoc_summary":true,"phpdoc_to_comment":true,"phpdoc_trim":true,"phpdoc_types":true,"phpdoc_var_without_name":true,"return_type_declaration":true,"self_accessor":true,"short_scalar_cast":true,"single_blank_line_before_namespace":true,"single_quote":true,"space_after_semicolon":true,"standardize_not_equals":true,"ternary_operator_spaces":true,"trim_array_spaces":true,"unary_operator_spaces":true,"whitespace_after_comma_in_array":true,"array_syntax":{"syntax":"short"},"linebreak_after_opening_tag":true,"modernize_types_casting":true,"no_multiline_whitespace_before_semicolons":true,"ordered_class_elements":true,"ordered_imports":true,"psr4":true,"strict_param":true},"hashes":{"src\/Connection.php":2839169415}}

‎.travis.yml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
language: php
2+
3+
env:
4+
- DB=mysql DB_HOST=mysql DB_DATABASE=testdb DB_USERNAME=root DB_PASSWORD=""
5+
6+
branches:
7+
only:
8+
- master
9+
- development
10+
11+
services:
12+
- mysql
13+
14+
php:
15+
- 5.6
16+
- 7.0
17+
- 7.1
18+
- nightly
19+
- hhvm
20+
21+
addons:
22+
hosts:
23+
- mysql
24+
25+
matrix:
26+
fast_finish: true
27+
allow_failures:
28+
- php: nightly
29+
- php: hhvm
30+
31+
install:
32+
- composer self-update
33+
- composer install
34+
35+
before_script:
36+
- if [[ "$DB" == "mysql" ]]; then mysql -e "CREATE DATABASE IF NOT EXISTS testdb;" -uroot; fi
37+
38+
script: php vendor/bin/codecept run --debug
39+
40+
cache:
41+
directories:
42+
- $HOME/.composer/cache

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) [year] [fullname]
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+158
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
[![Build Status](https://travis-ci.org/pharako/mysql-dbal.svg?branch=master)](https://travis-ci.org/pharako/mysql-dbal) [![Latest Stable Version](https://poser.pugx.org/pharako/mysql-dbal/v/stable)](https://packagist.org/packages/pharako/mysql-dbal) [![Total Downloads](https://poser.pugx.org/pharako/mysql-dbal/downloads)](https://packagist.org/packages/pharako/mysql-dbal) [![Latest Unstable Version](https://poser.pugx.org/pharako/mysql-dbal/v/unstable)](https://packagist.org/packages/pharako/mysql-dbal) [![License](https://poser.pugx.org/pharako/mysql-dbal/license)](https://packagist.org/packages/pharako/mysql-dbal)
2+
3+
MySQL DBAL
4+
==========
5+
6+
MySQL extensions for [Doctrine DBAL](https://github.com/doctrine/dbal).
7+
8+
`Pharako\DBAL\Connection` is an extension of `Doctrine\DBAL\Connection`, which means all functionality you get from the latter is also present in the former, with a few add-ons specific to MySQL:
9+
10+
* multiple inserts
11+
* single and multiple upserts (update records if they exist, insert them otherwise)
12+
13+
# Requirements
14+
15+
PHP 5.6 or above.
16+
17+
# Installation
18+
19+
Install via Composer:
20+
21+
```SHELL
22+
$ composer require pharako/mysql-dbal
23+
```
24+
25+
# Usage
26+
27+
## Instantiation and configuration
28+
29+
Most PHP frameworks will have some sort of *service injection* functionality to help you with configuration, but nothing stops you from doing it by hand.
30+
31+
### Manually
32+
33+
```PHP
34+
use Doctrine\Common\EventManager;
35+
use Doctrine\DBAL\Configuration;
36+
use Doctrine\DBAL\Driver\PDOMySql\Driver;
37+
use Pharako\DBAL\Connection;
38+
39+
$params = [
40+
'dbname' => 'my_db',
41+
'host' => 'localhost',
42+
'user' => 'username',
43+
'password' => '***',
44+
'driver' => 'pdo_mysql'
45+
];
46+
47+
$dbal = new Connection(
48+
$params,
49+
new Driver(),
50+
new Configuration(),
51+
new EventManager()
52+
);
53+
```
54+
55+
### Symfony 2 and above
56+
57+
Just specify the DBAL connection class under `wrapper_class` in `config.yml`. All the other configurations should remain the same:
58+
59+
```YAML
60+
doctrine:
61+
dbal:
62+
dbname: %database_name%
63+
host: %database_host%
64+
port: %database_port%
65+
user: %database_user%
66+
password: %database_password%
67+
driver: pdo_mysql
68+
wrapper_class: 'Pharako\DBAL\Connection'
69+
```
70+
71+
You can read [Doctrine DBAL Configuration](http://symfony.com/doc/current/reference/configuration/doctrine.html#doctrine-dbal-configuration) for more information on `wrapper_class` and other options.
72+
73+
# Extra functionality
74+
75+
Pharako's additional methods follow the structure of Doctrine's [data retrieval and manipulation](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/data-retrieval-and-manipulation.html) functionality, including [binding types](http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/data-retrieval-and-manipulation.html#binding-types).
76+
77+
## Multiple inserts
78+
79+
You can insert multiple records with one call - this will hit the database only once:
80+
81+
```PHP
82+
$data = [
83+
[
84+
'name' => 'Foo',
85+
'family_name' => 'Bar'
86+
],
87+
[
88+
'name' => 'Fuzz',
89+
'family_name' => 'Bazz'
90+
]
91+
];
92+
93+
$dbal->insert('my_table', $data);
94+
```
95+
96+
Or, if you want to specify the types of the inserted data:
97+
98+
```PHP
99+
$dbal->insert('my_table', $data, [\PDO::PARAM_STR, \PDO::PARAM_STR]);
100+
```
101+
102+
## Single and multiple upserts (update if present, insert if new)
103+
104+
Before using this functionality, make sure you read [*Careful with those upserts*](#careful-with-those-upserts) below.
105+
106+
Building on the previous example and assuming the `name` field is a unique key in the table structure, the first two records will have their `family_name` fields updated to `Rab` and `Zabb`, respectivelly, and the last one will be inserted:
107+
108+
```PHP
109+
$data = [
110+
[
111+
'name' => 'Foo',
112+
'family_name' => 'Rab'
113+
],
114+
[
115+
'name' => 'Fuzz',
116+
'family_name' => 'Zabb'
117+
],
118+
[
119+
'name' => 'New',
120+
'family_name' => 'Foo'
121+
]
122+
];
123+
124+
$dbal->upsert('my_table', $data);
125+
```
126+
127+
Again, this will hit the database only once.
128+
129+
If you want your upsert to update only a few columns and leave all the others untouched, you can pass it an array specifying those columns:
130+
131+
```PHP
132+
$data = [
133+
'who' => 'Them',
134+
'where' => 'There',
135+
'when' => 'Sometime',
136+
'why' => 'Because'
137+
];
138+
139+
$dbal->upsert(
140+
'another_table',
141+
$data,
142+
[\PDO::PARAM_STR, \PDO::PARAM_STR, \PDO::PARAM_STR, \PDO::PARAM_STR],
143+
['where', 'when']
144+
);
145+
```
146+
147+
In this example, if the upsert results in an update, only the `where` and `when` fields will be updated. If the upsert results in an insert, all fields will be included.
148+
149+
### Careful with those upserts
150+
151+
By and large, it is safe to execute upserts against tables of varied structures - those containing a single unique index, a multi-column unique index or even multiple unique indexes.
152+
153+
But, because upserts in MySQL are more involved than simple inserts and updates, you should **not** expect those methods to behave similarly in 100% of the cases (for example, `LAST_INSERT_ID()` in the context of an upsert may behave slightly differently than in that of an insert).
154+
155+
That's why the [official documentation](https://dev.mysql.com/doc/refman/5.7/en/insert-on-duplicate.html) says that "*In general, you should try to avoid using an `ON DUPLICATE KEY UPDATE` clause on tables with multiple unique indexes*" and *"[...] an `INSERT ... ON DUPLICATE KEY UPDATE` statement against a table having more than one unique or primary key is also marked as unsafe"*.
156+
157+
Despite that, upserts will work just as expected but in [edge case scenarios](http://bugs.mysql.com/bug.php?id=58637). If you want to play it extra safe, though, try to **tighten your tests** and make sure you get the expected results when the upsert inserts your records as well as when it (potentially) updates them.
158+

‎codeception.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
actor: Tester
2+
paths:
3+
tests: tests
4+
log: tests/_output
5+
data: tests/_data
6+
support: tests/_support
7+
envs: tests/_envs
8+
settings:
9+
bootstrap: _bootstrap.php
10+
colors: true
11+
memory_limit: 1024M
12+
extensions:
13+
enabled:
14+
- Codeception\Extension\RunFailed
15+
params:
16+
- env
17+
modules:
18+
config:
19+
Sequence:
20+
prefix: '_'
21+
Db:
22+
dsn: "mysql:host=%DB_HOST%;dbname=%DB_DATABASE%"
23+
user: "%DB_USERNAME%"
24+
password: "%DB_PASSWORD%"
25+
dump: 'tests/_data/dump.sql'
26+
populate: true
27+
cleanup: false
28+
reconnect: false
29+
enabled:
30+
- Sequence
31+
- Db

‎composer.json

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"name": "pharako/mysql-dbal",
3+
"description": "MySQL extensions for Doctrine DBAL",
4+
"keywords": [
5+
"doctrine", "dbal", "mysql", "upsert", "insert", "multiple"
6+
],
7+
"license": "MIT",
8+
"authors": [{
9+
"name": "Claudio Bizzotto"
10+
}],
11+
"require": {
12+
"php": ">=5.6",
13+
"doctrine/dbal": "^2.5"
14+
},
15+
"require-dev": {
16+
"codeception/codeception": "^2.2"
17+
},
18+
"autoload": {
19+
"psr-4": {
20+
"Pharako\\DBAL\\": "src/"
21+
}
22+
},
23+
"extra": {
24+
"branch-alias": {
25+
"dev-master": "0.1-dev"
26+
}
27+
}
28+
}

0 commit comments

Comments
 (0)