/**
* Return an instance with the specified path.
*
* This method MUST retain the state of the current instance, and return
* an instance that contains the specified path.
*
* The path can either be empty or absolute (starting with a slash) or
* rootless (not starting with a slash). Implementations MUST support all
* three syntaxes.
*
* If the path is intended to be domain-relative rather than path relative then
* it must begin with a slash ("/"). Paths not starting with a slash ("/")
* are assumed to be relative to some base path known to the application or
* consumer.
*
* Users can provide both encoded and decoded path characters.
* Implementations ensure the correct encoding as outlined in getPath().
*
* @param string $path The path to use with the new instance.
*
* @return static A new instance with the specified path.
* @throws \InvalidArgumentException for invalid paths.
*/
public function withPath($path)
{
if (!is_string($path)) {
throw new \InvalidArgumentException('URI Path should be a string.');
}
$path = (string) $path;
if (strpos($path, '?') !== false || strpos($path, '#') !== false) {
throw new \InvalidArgumentException('Path should not contain `?` and `#` symbols.');
}
$path = UriHelper::cleanPath($path);
$path = UriHelper::filterPath($path);
$new = clone $this;
$new->path = $path;
return $new;
}