PHP: rfc:hash.context.oop

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: OOP API for HashContext ======
  * Version: 1.0
  * Date: 2020-10-21
  * Author: Sara Golemon, pollita@php.net
  * Status: Under Discussion
  * First Published at: http://wiki.php.net/rfc/hash.context.oop

Provide methods on the already extant HashContext class.

===== Introduction =====

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.

===== Proposal =====

  * Make `HashContext::<nowiki>__</nowiki>construct()` a public method taking an identical signature to [[https://www.php.net/hash_init|hash_init()]].
  * Add new instance methods to the `HashContext` class:
    * `update(string $data): this`, mirroring [[https://www.php.net/hash_update|hash_update()]]
    * `updateFile(string $uri, ?StreamContext $context = null): this`, mirroring [[https://www.php.net/hash_update_file|hash_update_file()]]
    * `updateStream(Stream $stream, int $length = -1): this`, mirroring [[https://www.php.net/hash_update_stream|hash_update_stream()]]
    * `final(bool $raw_output = false): string`, mirroring [[https://www.php.net/hash_final|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.

===== Backward Incompatible Changes =====

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

===== Proposed PHP Version(s) =====

8.1

===== Open Issues =====

  * <nowiki>Name final() method as finalize()? __toString()?</nowiki>

===== Proposed Voting Choices =====

Straight up/down vote.

===== Patches and Tests =====

  * [[https://github.com/php/php-src/pull/6347|Pull Request#6347]]

===== Implementation =====

After the project is implemented, this section should contain 
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature
  - a link to the language specification section (if any)

===== References =====

  * [[https://externals.io/message/112034|Feature Request and discussion]]
Page Tools
