feat(multipart-stream): use types instead of runtime elements check

[simPod]

I propose to use types instead of throwing exceptions. When lib consumers respect types, those exceptions are never thrown.

[GrahamCampbell]

Thanks for the PR, but I even if we add those type annotations, we'd still want to properly enforce the types. I plan to re-work some of this in the next major version.

[simPod]

BTW what can I imagine under

to properly enforce the types

[GrahamCampbell]

We will throw ValuyeError someone passes something that makes it through the native type check but would fail the type in the phpdoc. This is similar to how many PHP internal functions work since PHP 8, such as passing a negative integer to a function that requires positive integers.

[simPod]

So you will keep runtime checks even in the next major version?

Personally I'd prefer to drop the code that checks whether a consumer is respecting types.

It should be consumer's responsibility to respect types so responsible users don't have to suffer such boilerplate.
If you pass a negative integer to something typed as positive-int ... well, it should be your problem only.

[GrahamCampbell]

Right, but the majority of people who use Guzzle don't know what static analyzers are and need the hand holding of things failing at runtime. I don't want to compromise on these principals of Guzzle being beginner friendly and supporting a wide range of PHP versions.

[mfn]

I would love to have at least the part of the PHP adding the phpdoc types.

But I also can understand this may not be desired (it's phpstan specific, next thing is someone maybe wants something psalm specific, etc.)