Standalone Input Filter classes and ZF2 Form Collections

While building some Zend\Form monstrosity with infinite* nested fieldsets and collections every which way I, the form (which uses externally-constructed InputFilters) would fail validation with no visible error messages. The problem? I was doing this:

$mainInputFilter = new InputFilter();
// Add the fields of my main-fieldset

$collectionInputFilter = new InputFilter();
// Add the fields of my sub-fieldset

$mainInputFilter->add($collectionInputFilter, 'collection-name');

When I should have been doing this:

$mainInputFilter = new InputFilter();
// Add the fields of my main-fieldset

$collectionInputFilter = new InputFilter();
// Add the fields of my sub-fieldset

$collectionContainerFilter = new CollectionInputFilter();
$collectionContainerFilter->setInputFilter($collectionInputFilter);

$mainInputFilter->add($collectionContainerFilter, 'collection-name');

Subtle difference makes all the difference. The InputFilter for the fieldset representing the elements of your Collection has to be added to a CollectionInputFilter, which then gets added to the InputFilter for the fieldset containing the Collection. Otherwise the validation will fail, but no errors are passed back to the form from the InputFilter (since no form elements match your mis-configured InputFilter), so you won't see the failed validation messages unless you var_dump a call to $form->getInputFilter()->getMessages()

Reminder to myself: Add this to the ZF2 docs when you get a chance

* = Tiny amount of hyperbole