DateTimeFormatter: Add option to return invalid date string unfiltered

[weierophinney]

• add documentation for DateTimeFormatter. Addresses Merge release 2.15.1 into 2.16.x #58.
• add @todo notation in docblock for $format property
• add tests for new option

• Are you fixing a bug?
  • Detail how the bug is invoked currently.

$filter = new DateTimeFormatter();
$filter->filter('2013-31-31'); // throws exception

• Detail the original, incorrect behavior.
  DateTimeFormatter::filter throws an exception in the event that the input is not a parsable date string
• Detail the new, expected behavior.

$filter = new DateTimeFormatter();
$filter->setThrowInvalidDateException(false);
$filter->filter('2013-31-31'); // returns "2013-31-31"

• Base your feature on the master branch, and submit against that branch.
• Add a regression test that demonstrates the bug, and proves the fix.
• Add a CHANGELOG.md entry for the fix.

---

Originally posted by @marcguyer at zendframework/zend-filter#84

[weierophinney]

@marcguyer This is a new feature because the exception was previously a desired result. Please use the develop branch instead.

---

Originally posted by @froschdesign at zendframework/zend-filter#84 (comment)

[gsteel]

This issue and its old PR is pretty stale - in 3.0 the behaviour is the same as the 2.x series so if anyone wants to implement the optional behaviour change, its best to target 3.0 now.

Ref #160