Back when the inclusion of libsodium in PHP 7.2 was announced, I was excited. A modern crypto library, with a modern, easy-to-use API? Unfortunately, calling the API "modern" meant something completely different to me than the libsodium binding actually delivers to its users.
Rather than a modern, mistake-proof API, it's a direct, low-level replacement for the unmaintained mcrypt library. It has more modern primitives, obscure names, and very little documentation. Although the extension was promoted to core years ago, the functions are all "Warning: this is undocumented" to this day. (Extension documentation is here.)
As for the names, I actually attended a libsodium talk at a PHP conference. The speaker covered which functions are asymmetric and which are symmetric, but I don't remember which is which without checking my notes. The docs say "Encrypt a message" for
sodium_crypto_secretbox. They also say that about
sodium_crypto_stream_xor, but that definitely sounds wrong.
I had been expecting an interface more like defuse/php-encryption (which I have used) or perhaps soatok/dhole-cryptography (which I have not.) Even if all the low-level crypto bits were exposed, because interoperability with other systems is important, I still expected a higher level API. I expected an "encrypt this text with that key" operation that took care of nonces, formatting details, and algorithm choices.