PHP RFC: OOP API for HashContext

• Version: 1.0
• Date: 2020-10-21
• Author: Sara Golemon, [email protected]
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/hash.context.oop

Provide methods on the already extant HashContext class.

As part of the long term effort to remove the resource type from PHP, the iterative hashing API provided by `hash_init()` et. al was converted to use object instances of the opaque class type `HashContext` for the PHP 7.2 release.

With the conversion to an object comes the opportunity to provide OOP interfaces to these APIs.

• Make `HashContext::__construct()` a public method taking an identical signature to hash_init().
• Add new instance methods to the `HashContext` class:
  • `update(string $data): this`, mirroring hash_update()
  • `updateFile(string $uri, ?StreamContext $context = null): this`, mirroring hash_update_file()
  • `updateStream(Stream $stream, int $length = -1): this`, mirroring hash_update_stream()
  • `final(bool $raw_output = false): string`, mirroring hash_final()

Note that the new update methods return the object instance to make using fluent method chaining easier rather that return bool or the number of bytes applied in the update. If they are unable to process the entire requested payload, they will throw an `Error` exception.

The psuedo classnames `Stream` and `StreamContext` here refer to what are currently resources wrapping `php_stream` and `php_stream_context`, respectively.

None. This does not change the API presented by the procedural hashing functions, and the only changes it makes to `HashContext` are additive.

8.1

• Name final() method as finalize()? __toString()?

Straight up/down vote.

• Pull Request#6347

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

• Feature Request and discussion