Exception interface

[abacaphiliac]

• add \RuntimeException wrapper.
• update all extensions of \RuntimeException to extend the wrapper.
• SPL-exception wrappers now implement a common exception interface for this package. this allows consumers to handle all custom exception types thrown by catching the common interface rather than by catching each specific extension or their SPL parents.
• add tests to validate existing exception hierarchy, in preparation for adjustment.
• add tests for changes to exception hierarchy.
• document exception interface in \JsonSchema\Constraints\ConstraintInterface.

as a consumer, this change will allow me to handle exceptions from this package like this:

try {
  $validator->check($value, $schema);
} catch (\JsonSchema\Exception\ExceptionInterface $exception) {
  // Handle all JsonSchema exceptions.
}

instead of this:

try {
  $validator->check($value, $schema);
} catch (\JsonSchema\Exception\InvalidArgumentException $exception) {
  // Handle all JsonSchema invalid-argument exceptions.
} catch (\JsonSchema\Exception\JsonDecodingException $exception) {
  // Handle JsonSchema decoding exception.
}
// Additional catch-blocks for all \RuntimeException children.

or worse:

try {
  $validator->check($value, $schema);
} catch (\InvalidArgumentException $exception) {
  // Handle all invalid-argument exceptions, not just JsonSchema exceptions.
} catch (\RuntimeException $exception) {
    // Handle all runtime-argument exceptions, not just JsonSchema exceptions.
} catch (\Exception $exception) {
    // Handle all exceptions, not just JsonSchema exceptions.
}

[bighappyface]

@abacaphiliac please rebase on master and push the changes to trigger the TravisCI build

[abacaphiliac]

@bighappyface thanks for having me do that. a couple of my tests did not pass in php53 and php54 because they use JSON constants that aren't available until php55. those 3 tests are now skipped in the php53 and php54 builds.

[bighappyface]

@abacaphiliac thanks for the rebase. Would you please now squash these three commits down to one?

[abacaphiliac]

@bighappyface done : )

i haven't tried this myself, but i've read that github now allows the project maintainer to configure squash requirements on merge requests, for a clean history. when enabled, it should give you a dropdown select on confirm merge to confirm squash and merge. have you tried it? are you able adjust settings in this project?

for reference:

• https://help.github.com/articles/about-pull-request-merge-squashing
• https://github.com/blog/2141-squash-your-commits

[bighappyface]

@abacaphiliac thanks for squashing down your commits.

Unfortunately I can not alter the settings of this repo to enable the squash option; however, while that github feature is nice, I believe a contributor is responsible for the condition of their own branch and PR.

I have time set aside next week to add a contributors file to set the appropriate expectations.

[bighappyface]

+1

@mirfilip @jojo198 @Maks3w what are your thoughts on this?

It looks like @abacaphiliac took the time to setup tests to verify the inclusion of the exception interface and wrapper do not introduce BC-breaking changes and I agree with the common interface approach.

Does this look like 2.1.0 material to you?

[Maks3w]

These series of test are best done as a dataProvider

[Maks3w]

This can be ok. Anyway:

1. I prefer don't declare LogicExceptions (like InvalidAr....) as I think they shouldn't be catched. As per PHP documentation "LogicExceptions should end with a change in your code".
2. Runtime exceptions usally are catched so its preferible document them in the code with @throws tags.
3. About to have a common interface I think is not very different from directly catch Exception or RuntimeException when you just want to catch any kind of unexpected situation

[bighappyface]

+1