diff --git a/README.md b/README.md index 43caa5a5335..8a1757886bb 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ | [![Code Coverage][Coverage image]][CodeCov 4.0] | [![Code Coverage][Coverage 3.1 image]][CodeCov 3.1] | [![Code Coverage][Coverage 2.13 image]][CodeCov 2.13] | | N/A | [![Code Coverage][TypeCov 3.1 image]][TypeCov 3.1] | N/A | -Powerful database abstraction layer with many features for database schema introspection, schema management and PDO abstraction. +Powerful ***D***ata***B***ase ***A***bstraction ***L***ayer with many features for database schema introspection and schema management. ## More resources: diff --git a/docs/en/reference/data-retrieval-and-manipulation.rst b/docs/en/reference/data-retrieval-and-manipulation.rst index fcef982d721..b879731c34d 100644 --- a/docs/en/reference/data-retrieval-and-manipulation.rst +++ b/docs/en/reference/data-retrieval-and-manipulation.rst @@ -1,10 +1,6 @@ Data Retrieval And Manipulation =============================== -Doctrine DBAL follows the PDO API very closely. If you have worked with PDO -before you will get to know Doctrine DBAL very quickly. On top of the API provided -by PDO there are tons of convenience functions in Doctrine DBAL. - Data Retrieval -------------- @@ -15,8 +11,7 @@ kind of API called PDO (PHP Data Objects). However because of disagreements between the PHP community there are often native extensions for each database vendor that are much more maintained (OCI8 for example). -Doctrine DBAL API builds on top of PDO and integrates native extensions by -wrapping them into the PDO API as well. If you already have an open connection +Doctrine DBAL API integrates native extensions. If you already have an open connection through the ``Doctrine\DBAL\DriverManager::getConnection()`` method you can start using this API for data retrieval easily. @@ -192,8 +187,7 @@ on the Connection, which are all described in the API section below. Binding Types ------------- -Doctrine DBAL extends PDOs handling of binding types in prepared statements -considerably. Besides ``Doctrine\DBAL\ParameterType`` constants, you +Besides ``Doctrine\DBAL\ParameterType`` constants, you can make use of two very powerful additional features. Doctrine\DBAL\Types Conversion @@ -228,10 +222,6 @@ which means this code works independent of the database you are using. List of Parameters Conversion ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This is a Doctrine 2.1 feature. - One rather annoying bit of missing functionality in SQL is the support for lists of parameters. You cannot bind an array of values into a single prepared statement parameter. Consider the following very common SQL statement: diff --git a/docs/en/reference/introduction.rst b/docs/en/reference/introduction.rst index 32dfc7a65e8..ac552a81618 100644 --- a/docs/en/reference/introduction.rst +++ b/docs/en/reference/introduction.rst @@ -1,17 +1,15 @@ Introduction ============ -The Doctrine database abstraction & access layer (DBAL) offers a -lightweight and thin runtime layer around a PDO-like API and a lot -of additional, horizontal features like database schema -introspection and manipulation through an OO API. - -The fact that the Doctrine DBAL abstracts the concrete PDO API away -through the use of interfaces that closely resemble the existing -PDO API makes it possible to implement custom drivers that may use -existing native or self-made APIs. For example, the DBAL ships with -a driver for Oracle databases that uses the oci8 extension under -the hood. +The Doctrine **D**ata**B**ase **A**bstraction **L**ayer (DBAL) offers an +object-oriented API and a lot of additional, horizontal features +like database schema introspection and manipulation. + +The fact that the Doctrine DBAL abstracts the access to the concrete +database away through the use of interfaces, makes it possible to implement +custom drivers that may use existing native or self-made APIs. +For example, the DBAL ships with a driver for Oracle databases that uses +the oci8 extension under the hood. The following database vendors are currently supported: @@ -21,9 +19,10 @@ The following database vendors are currently supported: - PostgreSQL - SQLite -The Doctrine 2 database layer can be used independently of the -object-relational mapper. In order to use the DBAL all you need is -the class loader provided by Composer, to be able to autoload the classes: +The Doctrine DBAL can be used independently of the +[Doctrine Object-Relational Mapper (ORM)](https://www.doctrine-project.org/projects/orm.html). +In order to use the DBAL all you need is +the class loader provided by [Composer](https://getcomposer.org/), to be able to autoload the classes: .. code-block:: php diff --git a/docs/en/reference/query-builder.rst b/docs/en/reference/query-builder.rst index 3c201df41d2..3b5bc687a16 100644 --- a/docs/en/reference/query-builder.rst +++ b/docs/en/reference/query-builder.rst @@ -1,7 +1,7 @@ SQL Query Builder ================= -Doctrine 2.1 ships with a powerful query builder for the SQL language. This QueryBuilder object has methods +Doctrine features a powerful query builder for the SQL language. This QueryBuilder object has methods to add parts to an SQL statement. If you built the complete state you can execute it using the connection it was generated from. The API is roughly the same as that of the DQL Query Builder. @@ -45,7 +45,7 @@ input to any of the methods of the QueryBuilder and use the placeholder .. note:: The numerical parameters in the QueryBuilder API start with the needle - ``0``, not with ``1`` as in the PDO API. + ``0``. Building a Query ---------------- diff --git a/docs/en/reference/security.rst b/docs/en/reference/security.rst index d8859e9a62c..dc6f9bb1d9c 100644 --- a/docs/en/reference/security.rst +++ b/docs/en/reference/security.rst @@ -90,7 +90,7 @@ Instead of using string concatenation to insert user-input into your SQL/DQL sta placeholders and then explain to the database driver which variable should be bound to which placeholder. Each database vendor supports different placeholder styles: -- All PDO Drivers support positional (using question marks) and named placeholders (:param1, :foo, :bar). +- All PDO Drivers support positional (using question marks) and named placeholders (e.g. ``:param1``, ``:foo``). - OCI8 only supports named parameters, but Doctrine DBAL has a thin layer around OCI8 and also allows positional placeholders. - Doctrine ORM DQL allows both named and positional parameters. The positional parameters however are not diff --git a/docs/en/reference/transactions.rst b/docs/en/reference/transactions.rst index 602a403b688..b06bba8d36f 100644 --- a/docs/en/reference/transactions.rst +++ b/docs/en/reference/transactions.rst @@ -1,10 +1,9 @@ Transactions ============ -A ``Doctrine\DBAL\Connection`` provides a PDO-like API for +A ``Doctrine\DBAL\Connection`` provides an API for transaction management, with the methods -``Connection#beginTransaction()``, ``Connection#commit()`` and -``Connection#rollBack()``. +``beginTransaction()``, ``commit()`` and ``rollBack()``. Transaction demarcation with the Doctrine DBAL looks as follows: @@ -135,10 +134,10 @@ wider scope and the control is handed to the outer scope. .. warning:: - Directly invoking ``PDO#beginTransaction()``, - ``PDO#commit()`` or ``PDO#rollBack()`` or the corresponding methods - on the particular ``Doctrine\DBAL\Driver\Connection`` instance in - use bypasses the transparent transaction nesting that is provided + Directly invoking ``PDO::beginTransaction()``, + ``PDO::commit()`` or ``PDO::rollBack()`` or the corresponding methods + on the particular ``Doctrine\DBAL\Driver\Connection`` instance + bypasses the transparent transaction nesting that is provided by ``Doctrine\DBAL\Connection`` and can therefore corrupt the nesting level, causing errors with broken transaction boundaries that may be hard to debug.