Deprecation and forward compat for flush

[malarzm]

We missed this originally. Patch also includes forward compatibility layer so consumers may pass $options as a first argument already. Also there's a chance I should have placed similar code in UnitOfWork::commit although I haven't thought about any legit reason to call it directly instead of DocumentManager::flush so I didn't bother

[malarzm]

I'm not sure about wording here

[alcaeus]

We should only trigger the deprecation notice if documents were passed:

Suggested change

	if (func_num_args() === 2) {
	elseif (func_num_args() === 2) {

[malarzm]

Not necessarily, $dm->flush(null, $options); will stop working as well and folks can call $dm->flush($options); now

[alcaeus]

As is, $dm->flush([$document], $options); throws two deprecation warnings. We should make sure this doesn't happen as it might confuse the user.

As I write this, we should also make sure to gracefully handle $dm->flush([], $options); to make sure we don't treat it as the "user passed documents" case.

[rieschl]

It seems that passing an array of documents is an undocumented feature. I didn't find anything in the documentation and the method signature mentions just one object. Only deep down in the UoW is the check if the parameter is an array. So did anyone even use that?

[malarzm]

Hard to say, but there's a chance :)

[alcaeus]

Suggested change

	'$options will become a first argument in doctrine/mongodb-odm 2.0, you may pass it as first now.',
	sprintf('Flushing selected documents has been deprecated and will be removed in doctrine/mongodb-odm 2.0. You can omit the first argument to %s.', __METHOD__),