API improvement suggestions

[divarvel]

Hi, following #2 and #3, here is a bit of feedback:

api simplification

• merge KeyPair::newWithAlgorithm with the constructor, with an optional argument
• merge addCode and addCodeWithParams, leveraging optional arguments
• allow providing code (and optionally params) in all *Builder constructors

// before
 $tokenBuilder = new BiscuitBuilder();
 $tokenBuilder->addCodeWithParams('user({id})', ['id' => 'payment-api'], []);

// after
$tokenBuilder = new BiscuitBuilder('user({id})', ['id' => 'payment-api']);

performance improvements

• instead of cloning in all add* operations, the PHP builder structures could wrap the rust builder in an option and use take to consume the underlying builder. That’s a bit cumbersome, but that’s how we do it in biscuit-python: https://github.com/eclipse-biscuit/biscuit-python/blob/main/src/lib.rs#L200

I’m not sure what is the impact of cloning here, in comparison with crossing the PHP-rust boundary, so this might not be that useful, but at least that’s the intended way of using the builder structs in a language with no borrow checker. Merging addCode and addCodeWithParams first would reduce the work needed for this change

new features

• key selection: the most generic way to do that would be through a PHP Callable taking the (optional) root key id and returning the corresponding public key. Another, lighter way would be to provide an array mapping key ids to public keys.
• extern calls: since ext-php-rs allows calling PHP from rust, this should be feasible
• structured exceptions: it’s a wip in biscuit-python: wip: demo structured data in exceptions eclipse-biscuit/biscuit-python#43