[Summary view] [Print] [Text view]

   1  # Aura.Sql
   2  
   3  Provides an extension to the native [PDO](http://php.net/PDO) along with a
   4  profiler and connection locator. Because _ExtendedPdo_ is an extension of the
   5  native _PDO_, code already using the native _PDO_ or typehinted to the native
   6  _PDO_ can use _ExtendedPdo_ without any changes.
   7  
   8  Added functionality in _Aura.Sql_ over the native _PDO_ includes:
   9  
  10  - **Lazy connection.** _ExtendedPdo_ connects to the database only on
  11    method calls that require a connection. This means you can create an
  12    instance and not incur the cost of a connection if you never make a query.
  13  
  14  - **Decoration.** _DecoratedPdo_ can be used to decorate an existing PDO
  15    instance. This means that a PDO instance can be "extended" **at runtime** to
  16    provide the _ExtendedPdo_ behaviors.
  17  
  18  - **Array quoting.** The `quote()` method will accept an array as input, and
  19    return a string of comma-separated quoted values.
  20  
  21  - **New `perform()` method.** The `perform()` method acts just like `query()`,
  22    but binds values to a prepared statement as part of the call.  In addition,
  23    placeholders that represent array values will be replaced with comma-
  24    separated quoted values. This means you can bind an  array of values to a
  25    placeholder used with an `IN (...)`  condition when using `perform()`.
  26  
  27  - **New `fetch*()` methods.** The new `fetch*()` methods provide for
  28    commonly-used fetch actions. For example, you can call `fetchAll()` directly
  29    on the instance instead of having to prepare a statement, bind values,
  30    execute, and then fetch from the prepared statement. All of the `fetch*()`
  31    methods take an array of values to bind to to the query statement, and use
  32    the new `perform()` method internally.
  33  
  34  - **New `yield*()` methods.** These are complements to the `fetch*()` methods
  35    that `yield` results instead of `return`ing them.
  36  
  37  - **Exceptions by default.** _ExtendedPdo_ starts in the `ERRMODE_EXCEPTION`
  38    mode for error reporting instead of the `ERRMODE_SILENT` mode.
  39  
  40  - **Profiler.** An optional query profiler is provided, along with an
  41    interface for other implementations, that logs to any PSR-3 interface.
  42  
  43  - **Connection locator.** A optional lazy-loading service locator is provided
  44    for picking different database connections (default, read, and write).
  45  
  46  
  47  ## Installation and Autoloading
  48  
  49  This package is installable and PSR-4 autoloadable via Composer as
  50  [aura/sql][].
  51  
  52  Alternatively, [download a release][], or clone this repository, then map the
  53  `Aura\Sql\` namespace to the package `src/` directory.
  54  
  55  ## Dependencies
  56  
  57  This package requires PHP 5.6 or later; it has also been tested on PHP 7 and
  58  HHVM. We recommend using the latest available version of PHP as a matter of
  59  principle.
  60  
  61  Aura library packages may sometimes depend on external interfaces, but never on
  62  external implementations. This allows compliance with community standards
  63  without compromising flexibility. For specifics, please examine the package
  64  [composer.json][] file.
  65  
  66  ## Quality
  67  
  68  [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/auraphp/Aura.Sql/badges/quality-score.png?b=3.x)](https://scrutinizer-ci.com/g/auraphp/Aura.Sql/)
  69  [![Code Coverage](https://scrutinizer-ci.com/g/auraphp/Aura.Sql/badges/coverage.png?b=3.x)](https://scrutinizer-ci.com/g/auraphp/Aura.Sql/)
  70  [![Build Status](https://travis-ci.org/auraphp/Aura.Sql.png?branch=3.x)](https://travis-ci.org/auraphp/Aura.Sql)
  71  [![PDS Skeleton](https://img.shields.io/badge/pds-skeleton-blue.svg?style=flat-square)](https://github.com/php-pds/skeleton)
  72  
  73  This project adheres to [Semantic Versioning](http://semver.org/).
  74  
  75  To run the unit tests at the command line, issue `composer install` and then
  76  `./vendor/bin/phpunit` at the package root. (This requires [Composer][] to be
  77  available as `composer`.)
  78  
  79  This package attempts to comply with [PSR-1][], [PSR-2][], and [PSR-4][]. If
  80  you notice compliance oversights, please send a patch via pull request.
  81  
  82  ## Community
  83  
  84  To ask questions, provide feedback, or otherwise communicate with other Aura
  85  users, please join our [Google Group][], follow [@auraphp][], or chat with us
  86  on Freenode in the #auraphp channel.
  87  
  88  ## Documentation
  89  
  90  This package is fully documented [here](./docs/index.md).
  91  
  92  [PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
  93  [PSR-2]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
  94  [PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md
  95  [Composer]: http://getcomposer.org/
  96  [Google Group]: http://groups.google.com/group/auraphp
  97  [@auraphp]: http://twitter.com/auraphp
  98  [download a release]: https://github.com/auraphp/Aura.Sql/releases
  99  [aura/sql]: https://packagist.org/packages/aura/sql
 100  [composer.json]: ./composer.json