New 3.0.x; removing HHVM support; minimum PHP 7.1

.gitignore

@@ -1,4 +1,3 @@
-/nbproject/private/
 /vendor/
 /build/
 /composer.lock

.travis.yml

@@ -1,24 +1,22 @@
 sudo: required
 dist: trusty
+services:
+  - mongodb
 language: php
 php:
-  - 7
-  - hhvm
-matrix:
-    allow_failures:
-        - php: hhvm
+  - 7.1
+  - 7.2
 before_install:
   - composer self-update
 install:
   - composer update --ignore-platform-reqs --prefer-source
 before_script:
-  - if [[ $TRAVIS_PHP_VERSION != "hhvm" ]]; then phpenv config-add travis-php.ini; fi
-  - if [[ $TRAVIS_PHP_VERSION = "hhvm" ]]; then sudo cat travis-php.ini >> /etc/hhvm/php.ini; ./build-mongodb.sh; fi
+  - phpenv config-add travis-php.ini
 script:
   - vendor/bin/phpunit --coverage-clover=coverage.clover
 after_script:
-  - sh -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then wget https://scrutinizer-ci.com/ocular.phar; fi;'
-  - sh -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then php ocular.phar code-coverage:upload --format=php-clover coverage.clover; fi;'
+  - wget https://scrutinizer-ci.com/ocular.phar
+  - php ocular.phar code-coverage:upload --format=php-clover coverage.clover
 cache:
   directories:
     - $HOME/.composer/cache

README.md

@@ -9,8 +9,7 @@ This is its Data Access Object support component. You can use these classes to s
 [![Build Status](https://travis-ci.org/libreworks/caridea-dao.svg)](https://travis-ci.org/libreworks/caridea-dao)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/libreworks/caridea-dao/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/libreworks/caridea-dao/?branch=master)
 [![Code Coverage](https://scrutinizer-ci.com/g/libreworks/caridea-dao/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/libreworks/caridea-dao/?branch=master)
-
-We've also included `.hhi` files for the Hack typechecker.
+[![Documentation Status](http://readthedocs.org/projects/caridea-dao/badge/?version=latest)](http://caridea-dao.readthedocs.io/en/latest/?badge=latest)
 
 ## Installation
 
@@ -20,14 +19,19 @@ You can install this library using Composer:
 $ composer require caridea/dao
 ```
 
-* The master branch (version 2.x) of this project requires PHP 7.0 and depends on `caridea/event`.
+* The master branch (version 3.x) of this project requires PHP 7.1 and depends on `caridea/event`.
+* Version 2.x of this project requires PHP 7.0 and depends on `caridea/event`.
 
 ## Compliance
 
 Releases of this library will conform to [Semantic Versioning](http://semver.org).
 
 Our code is intended to comply with [PSR-1](http://www.php-fig.org/psr/psr-1/), [PSR-2](http://www.php-fig.org/psr/psr-2/), and [PSR-4](http://www.php-fig.org/psr/psr-4/). If you find any issues related to standards compliance, please send a pull request!
 
+## Documentation
+
+* Head over to [Read the Docs](http://caridea-dao.readthedocs.io/en/latest/)
+
 ## Features
 
 We provide a mechanism to translate vendor-specific exceptions (right now, MongoDB and Doctrine exceptions) into a standard exception hierarchy.
@@ -56,4 +60,4 @@ class MyDao extends \Caridea\Dao\MongoDb
         });
     }
 }
-```
+```

composer.json

@@ -13,22 +13,22 @@
     ],
     "extra": {
         "branch-alias": {
-            "dev-master": "2.1.x-dev"
+            "dev-master": "3.0.x-dev"
         }
     },
     "require": {
-        "php": ">=7.0.0",
+        "php": ">=7.1.0",
         "psr/log": "^1.0",
-        "caridea/event": "^2.1"
+        "caridea/event": "^3.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^5.2.0",
-        "libreworks/psr3-log-hhi": "^1.0.0",
-        "libreworks/ext-mongodb-hhi": "^1.1.0",
-        "mongodb/mongodb": "1.1.x-dev"
+        "phpunit/phpunit": "^6.0.0",
+        "doctrine/orm": "^2.0.0",
+        "mongodb/mongodb": "^1.2.0"
     },
     "suggest": {
         "ext-mongodb": "Allows use of MongoDB DAO",
+        "doctrine/orm": "Allows use of Doctrine2 DAO",
         "mongodb/mongodb": "In case you want to make life easier for yourself"
     },
     "autoload": {

docs/01-exceptions.md

@@ -0,0 +1,28 @@
+# Exception Hierarchy
+
+We provide a mechanism to translate vendor-specific exceptions into a standard exception hierarchy.
+
+## Reason
+
+It's all about separation of concerns and abstraction. Using the translation utilities in this library, you can wrap vendor-specific exceptions in these generic exceptions.
+
+It decouples your persistence layer from the rest of your application. You can swap out the library you use to store data and not have to worry about changes in the rest of your application.
+
+## Exception Classes
+
+All of the following classes are in the `Caridea\Dao\Exception` namespace:
+
+* `Inoperable` – An exception for invalid API usage and configuration problems (extends from `\LogicException`)
+* `Transient` – An abstract super class for problems that might not occur a second time (extends from `\RuntimeException`)
+  * `Conflicting` – An exception for concurrency failures
+  * `Unreachable` – An exception for connection problems
+* `Permanent` – An abstract super class for problems that will probably occur a second time (extends from `\RuntimeException`)
+  * `Generic` – An exception for any other problem not covered elsewhere
+  * `Locked` – An exception for unwritable records
+  * `Unretrievable` – An exception for unexpected results, for instance no results or too many results
+  * `Violating` – An exception for constraint violations
+    * `Duplicative` – An exception for unique constraint violations
+
+## Translators
+
+We distribute two translation utilities with this library: one for the popular [Doctrine ORM library](http://www.doctrine-project.org/), the other for the popular [MongoDB library](https://github.com/mongodb/mongo-php-library).

docs/02-daos.md

@@ -0,0 +1,88 @@
+# Abstract DAO Classes
+
+This library comes with two super-classes to be extended by your own projects:
+
+* `Caridea\Dao\Doctrine2` – designed for the popular [Doctrine ORM library](http://www.doctrine-project.org/)
+* `Caridea\Dao\MongoDb` – designed for the popular [MongoDB library](https://github.com/mongodb/mongo-php-library)
+
+They both extend from `Caridea\Dao\Dao`, which is an abstract class that implements `Psr\Log\LoggerAwareInterface`.
+
+## Doctrine
+
+The Doctrine DAO constructor takes the `Doctrine\ORM\EntityManager`, the name of the entity, and an optional `Psr\Log\LoggerInterface`. Once created, the following protected properties are available to subclasses:
+
+* `$manager` – The `EntityManager` you provided
+* `$entityName` – The `string` entity name you provided
+* `$repository` – A `Doctrine\ORM\EntityRepository` retrieved from the `EntityManager`
+* `$logger` – A `Psr\Log\LoggerInterface`, guaranteed to be non-null
+
+There are also two very useful protected methods available to subclasses.
+
+### The doExecute Method
+
+The `doExecute` method accepts a `Closure` that gets passed the `EntityManager`.
+
+If an exception occurs while your function is being executed, it's translated and wrapped by one of the exceptions included in this library.
+
+```php
+class MyDao extends \Caridea\Dao\Doctrine2
+{
+    public function create($record)
+    {
+        $this->logger->info("Creating the record");
+        $this->doExecute(function ($manager) use ($record) {
+            $manager->persist($record);
+            $manager->flush();
+        });
+    }
+}
+```
+
+### The doExecuteInRepository Method
+
+Similarly, the `doExecuteInRepository` method accepts a `Closure` that gets passed the `EntityRepository`.
+
+If an exception occurs while your function is being executed, it's translated and wrapped by one of the exceptions included in this library.
+
+```php
+class MyDao extends \Caridea\Dao\Doctrine2
+{
+    public function find($id)
+    {
+        return $this->doExecuteInRepository(function ($repository) {
+            return $repository->find($id);
+        });
+    }
+}
+```
+
+## MongoDB
+
+The MongoDB DAO constructor takes the `MongoDB\Driver\Manager`, the name of the collection, and an optional `Psr\Log\LoggerInterface`. Once created, the following protected properties are available to subclasses:
+
+* `$manager` – The `Manager` you provided
+* `$collection` – The `string` collection name you provided
+* `$logger` – A `Psr\Log\LoggerInterface`, guaranteed to be non-null
+
+There are also a very useful protected method available to subclasses.
+
+### The doExecute Method
+
+The `doExecute` method accepts a `Closure` that gets passed the `Manager` and collection name.
+
+If an exception occurs while your function is being executed, it's translated and wrapped by one of the exceptions included in this library.
+
+```php
+class MyDao extends \Caridea\Dao\MongoDb
+{
+    public function create($record)
+    {
+        $this->logger->info("Creating the record");
+        $this->doExecute(function ($manager, $collection) use ($record) {
+            $bulk = new \MongoDB\Driver\BulkWrite();
+            $bulk->insert($record);
+            return $manager->executeBulkWrite($collection, $bulk);
+        });
+    }
+}
+```

docs/03-events.md

@@ -0,0 +1,49 @@
+# Events
+
+This library includes several events that can be broadcast, and a trait you can use in your DAOs to broadcast these events.
+
+## Event Classes
+
+The following classes are all in the `Caridea\Dao\Event` namespace. They all extend from the `Caridea\Dao\Event` class, which includes a method: `getEntity` that returns the entity involved.
+
+* `PreDelete` – To be broadcast before a delete event
+* `PostDelete` – To be broadcast after a delete event
+* `PreInsert` – To be broadcast before an insert event
+* `PostInsert` – To be broadcast after an insert event
+* `PreUpdate` – To be broadcast before an update event
+* `PostUpdate` – To be broadcast after an update event
+
+## Publishing Trait
+
+The `Caridea\Dao\Event\Publishing` trait has methods your DAO can call that publish the above events. They all accept a single argument that is the entity involved.
+
+* `preDelete` – publishes a `PreDelete` event
+* `postDelete` – publishes a `PostDelete` event
+* `preInsert` – publishes a `PreInsert` event
+* `postInsert` – publishes a `PostInsert` event
+* `preUpdate` – publishes a `PreUpdate` event
+* `postUpdate` – publishes a `PostUpdate` event
+
+Here's an example class that uses this trait:
+
+```php
+class MyDao extends \Caridea\Dao\MongoDb implements \Caridea\Event\PublisherAware
+{
+    use \Caridea\Dao\Event\Publishing;
+
+    public function create($record)
+    {
+        $this->preInsert($record);
+        $this->doExecute(function () {
+            // do some persistence magic
+        });
+        $this->postInsert($record);
+    }
+}
+```
+
+When creating an instance of this class, you'd want to make sure to call `setPublisher`, or better yet, use [caridea/container](https://github.com/libreworks/caridea-container) to factory your DAO.
+
+## But My Persistence Library Has Events…
+
+Awesome! Don't use this trait, then! If your library (e.g. Doctrine) already handles events that occur to entities, then this trait becomes irrelevant.

docs/index.md

@@ -0,0 +1,9 @@
+# caridea/dao
+
+🍤 Caridea is a miniscule PHP application library. This shrimpy fellow is what you'd use when you just want some helping hands and not a full-blown framework.
+
+This is its Data Access Object support library. You can use these classes to support DAOs that you write.
+
+* [Exception Hierarchy](01-exceptions.md)
+* [Abstract DAO Classes](02-daos.md)
+* [Events](03-events.md)