Add an OOP API to HashContext

[sgolemon]

Preliminary to writing up an RFC and following up on this thread: https://externals.io/message/112034

Summary:

• Added OOP methods:

  • __construct() - Same signature as hash_init, calling new HashContext(...) should be equivalent to hash_init(same args)

  • update/updateStream/updateFile() - Same parameters as functional API without having to pass the object.

    • Unlike functional APIs, these return $this for fluent calling. If an error is encountered, an exception is thrown.

  • final() - Exactly like calling hash_final($ctx)

  • getAlgo() - Returns the name of the hashing algorithm in use.

I resisted the urge to add static methods echoing APIs like hash_algos() as this didn't seem to add much, if anything.

[divinity76]

i think the failing test is just a stupid DIRECTORY_SEPARATOR issue in string(%s) "Error opening '%s/does-not-exist.txt'"

could just let %s take care of it,
or if you really want to ensure that there's a directory separator there, maybe something like

string(%s) "Error opening '%r.*?(?:\\|\/)%rdoes-not-exist.txt'"

[TysonAndre]

Didn't see any issues, just one nit on folding brackets.

Overall, it seems like an improvement and a less error-prone alternate API

[TysonAndre]

Suggested change

	/* {{{ */
	/* }}} */

[azjezz]

Unlike functional APIs, these return $this for fluent calling.

What about making the context immutable? I have implemented a HashContext similar to this recently in PSL, with an immutable API: https://github.com/azjezz/psl/blob/8eece3a3c289922622136ec24d3e21c63b34a9ac/src/Psl/Hash/Context.php#L18-L31

this means whenever a function recieve an instance of Hash\Context, there's no need to check if it's valid or not, because it's always valid.

with this implementation, if i write a function that is supposed to take a HashContext, i can never be sure if it is valid or not.

[divinity76]

try

				zend_throw_exception_ex(NULL, 0, "Stream read encountered error, " ZEND_LONG_FMT " byte(s) copied", didread);

(something about 32bit zend_long printf format, check line 57 & 86 here here https://github.com/php/php-src/blob/master/Zend/zend_long.h#L57 )

[divinity76]

@azjezz

What about making the context immutable?

i oppose this idea. i do not want the vanilla HashContext immutable.

this would result in quite a few more malloc()+memcpy()'s for the "common" case of ->update(),
it would basically incur the overhead of hash_copy() on every hash_update() invocation.

• to be clear, i would not oppose (nor would i endorse, i would just ignore the discussion) the inclusion of a HashContextImmutable in core php, but i don't want the vanilla HashContext to be immutable.

• also could mention that my opinions doesn't matter much, i'm not a core dev and not on an rfc voting list or anything like that ^^

[cmb69]

What's the status here? There are merge conflicts, and the PR might need an RFC (IMO it does).

[iluuu1994]

Closing as there was no response.