prismicio/php-kit — pull request #84 by tremby (2014-12-25 00:29:15+00:00)
Title: SearchForm#set: return self

This is is a fix to SearchForm's set method to return itself rather than a new instance, as per its own documentation.

The bug report I was going to submit follows:

------

I'm building up a search form, predicate by predicate. I like to do this on separate lines of code, since that makes it easy to wrap some lines in conditionals, for example.

I got caught up just now because the query method returns a new instance rather than modifying and returning itself, due to the set method doing that.

Presuming I do want to split it into separate lines, instead of being able to do
```
$form = $api->forms()->everything;
$form->ref($api->master());
$form->query(Predicate::....);
$form->query(Predicate::...);
$result = $form->submit();
```

I have to do
```
$form = $api->forms()->everything;
$form = $form->ref($api->master());
$form = $form->query(Predicate::...);
$form = $form->query(Predicate::...);
$result = $form->submit();
```
which seems very awkward.

Even the documentation of $searchForm->set() (which both of these methods use) suggests it modifies the existing object, but in fact it doesn't. https://github.com/prismicio/php-kit/blob/master/src/Prismic/SearchForm.php#L66

```
/**
* Sets a value for a given parameter. For instance: set('orderings', '[product.price]'),
* or set('page', 2).
*
* Checks that the parameter is expected in the RESTful form before allowing to add it.
*
* @api
* @param string $key the name of the parameter
* @param string $value the value of the parameter
* @throws \RuntimeException
* @return \Prismic\SearchForm the current SearchForm object, with the new parameter added
*/
```
"return the current SearchForm object" -- this is not what it does. It'd be a lot more useful if it did.

Incidentally, there's a case where currently it returns null. I wonder if this should in fact be throwing an exception or returning the unmodified $this.