Allow API parameter type hints

[sgiehl]

Summary

Currently it is not possible to use type hints in API methods. As all parameters are parsed from the request, they are currently always either a string or an array. Adding type hints other then string or array would though currently end up in an error of mismatching types.

Allowing type hinting for API methods would help us solve a plenty of issues around incorrect parameter types. In the past we had a lot issues like that, where e.g. someone passed an array as period or date parameter (e.g. like #19222), causing the API to throw an uncaught exception, as it was used in a way, where an array couldn't be handled.

To implement that we could simply do some parameter validation in the API proxy, based on the type hint we can receive using reflection. Passing that type to Common::getRequestVar, which we use, to receive all parameter values should do the trick.
Needs to be changed somewhere around here:

matomo/core/API/Proxy.php

Lines 409 to 441 in a01eea3

	private function getRequestParametersArray($requiredParameters, $parametersRequest)
	{
	$finalParameters = array();
	foreach ($requiredParameters as $name => $defaultValue) {
	try {
	if ($defaultValue instanceof NoDefaultValue) {
	$requestValue = Common::getRequestVar($name, null, null, $parametersRequest);
	} else {
	try {
	if ($name == 'segment' && !empty($parametersRequest['segment'])) {
	// segment parameter is an exception: we do not want to sanitize user input or it would break the segment encoding
	$requestValue = ($parametersRequest['segment']);
	} else {
	$requestValue = Common::getRequestVar($name, $defaultValue, null, $parametersRequest);
	}
	} catch (Exception $e) {
	// Special case: empty parameter in the URL, should return the empty string
	if (isset($parametersRequest[$name])
	&& $parametersRequest[$name] === ''
	) {
	$requestValue = '';
	} else {
	$requestValue = $defaultValue;
	}
	}
	}
	} catch (Exception $e) {
	throw new Exception(Piwik::translate('General_PleaseSpecifyValue', array($name)));
	}
	$finalParameters[$name] = $requestValue;
	}
	return $finalParameters;
	}

Note: This issue is not about adding type hints to all our API methods. For now we should only provide the possibility, so we can add it when already working on certain APIs later.

@mattab I've discussed this improvement today with @tsteur and @justinvelluppillai
It would be awesome to include this in Matomo 5. We could in theory also do it in a later release, but if we need to add a type hint in a plugin then, we would need to increase the minimum required version, to the version where this got implemented.

I already had a look at the code, and it should only take around 2 hours to implement that.