File::encrypt implementation vs secretstream

[stidges]

First of all thank you for this comprehensive library and the libsodium guide, I've been deep diving into it lately and these really helped me to understand the library better!

When reading through the libsodium documentation I came across the sodium_crypto_secretstream_* methods. These methods allow the user to encrypt/decrypt streams easily (reference implementation from the readme). I was wondering, do you think these methods are a good option to use for encrypting and decrypting files, or do you think the File::encrypt(...) implementation Halite provides is a more secure option?

[paragonie-scott]

Having recently ported these APIs to sodium_compat, my opinion is: You should probably use secretstream.

They both solve the problem securely, but Halite is currently only implemented in PHP.

[alecwcp]

@paragonie-scott Could you explain why secretstream is preferable to using File::encrypt(...)?
From what I can see File::encrypt(...) uses sodium_crypto_stream_xor - is there any reason for using this rather than using the sodium_crypto_secretstream_* methods as used here https://github.com/jedisct1/libsodium-php#encrypt-a-file-using-a-secret-key ?