require-api: requireOne, requireOneByXXX, requireByArray

[mpscholten]

Implementation of #803

This adds requireOne(), requireOneBy($column, $value) and requireOneByArray($values) to ModelCriteria. The ModelCriteria also provides magic methods for requireOneByXXX and requireOneByXXXAndXXX. The generated query classes have @method-annotations for these magic methods to support autocompletion.

---

You can now do something like:

<?php
// ...
try {
  echo 'Hello ' . UserQuery::create()->requireOneById($_GET['id'])->getName();
} catch (\Propel\Runtime\Exception\ModelNotFoundException $e) {
  echo $e->getMessage();
}

Which will output 'Hello Marc' or 'User could not be found' depending on whenever the given user-id exists.

---

You can customize the exception class in the propel config:

propel
    generator:
        objectModel:
            notFoundExceptionClass: \Vendor\Project\ResourceNotFoundException

or by overwriting the modelNotFoundExceptionClass attribute in your query class (or you can overwrite the createModelNotFoundException method to customize your exception even more, e.g. when you use a custom constructor signature)

[marcj]

You could check it with $this->isWithOneToMany() and throw a exception for that case.

[mpscholten]

This should be handled in the $this->findOne method. I just copied the description from the findOne methods because the require methods just wrap the findOne methods.

This should be fixed in it's own pull request.

[marcj]

Ah I see :)

[marcj]

Nice, I like it. I however don't like the term "model" in ModelNotFoundException, the model is actually the class struct and not the data/instance that is defined by its class/schema. I'd rather go with EntityNotFoundException.

[staabm]

👍 for EntityNotFoundException

[mpscholten]

The phpdoc of findOne says it "[...] returns a model object." so I used ModelNotFoundException to keep the identifiers consistent. But I'm fine with changing the exception :)

[marcj]

Excellent @mpscholten! When you are gonna squash those commits I'm going to merge this beauty. 😄

[mpscholten]

When the discussion in #803 is finished :) But I think we will just take the require syntax.

I haven't rebased yet because I already use this feature and the rebase would change the commit-hash my code is requiring in the composer lock file. But here we go! :)

[marcj]

Thanks, great job :)