s9e / bencode
Fast and efficient bencode decoder/encoder, designed to handle malformed and malicious input gracefully.
2.3.2
2024-04-09 19:49 UTC
Requires
- php: >=8.1
Requires (Dev)
- nikic/php-fuzzer: *
- phpunit/phpunit: ^10.0
- s9e/repdoc: dev-wip
README
s9e\Bencode is a clean and efficient Bencode encoder/decoder. It is designed to handle malformed and malicious input gracefully.
Installation
composer require s9e/bencode
Usage
Decode a bencoded string
use s9e\Bencode\Bencode; print_r(Bencode::decode('d3:bar4:spam3:fooi42ee'));
ArrayObject Object
(
[storage:ArrayObject:private] => Array
(
[bar] => spam
[foo] => 42
)
)
Encode a PHP value
use s9e\Bencode\Bencode; print_r(Bencode::encode(['foo' => 42, 'bar' => 'spam']));
d3:bar4:spam3:fooi42ee
Supported types are as follow:
array
,int
, andstring
values are encoded natively.float
values that can be losslessly converted to integers are coerced toint
.bool
values are coerced toint
.- An object that implements
s9e\Bencode\BencodeSerializable
is encoded as the value returned by itsbencodeSerialize()
method. - The properties of an
stdClass
object are encoded in a dictionary. - An instance of
ArrayObject
is treated as an array.
use s9e\Bencode\Bencode; use s9e\Bencode\BencodeSerializable; $bencodable = new class implements BencodeSerializable { public function bencodeSerialize(): array|int|string { return 42; } }; print_r(Bencode::encode($bencodable));
i42e
Handle exceptions
try { s9e\Bencode\Bencode::decode('i123x'); } catch (s9e\Bencode\Exceptions\DecodingException $e) { var_dump($e->getMessage(), $e->getOffset()); }
string(29) "Illegal character at offset 4"
int(4)
try { s9e\Bencode\Bencode::encode(2.5); } catch (s9e\Bencode\Exceptions\EncodingException $e) { var_dump($e->getMessage(), $e->getValue()); }
string(17) "Unsupported value"
float(2.5)
Salvage non-compliant input
By default, the decoder rejects non-compliant input with a ComplianceError
exception, which is a subtype of DecodingException
. If you have to handle input produced by a non-compliant encoder, the decodeNonCompliant
method may be able to salvage it by replacing illegal values as follow:
- Unordered dictionaries are automatically sorted.
- Duplicate entries in dictionaries overwrite prior entries.
- Integers used as dictionary keys are converted to strings.
- Leading
0
s are removed from integers. - Negative zero is converted to
0
. - Trailing junk at the end of the input is ignored.
In the following example, we try to load an invalid dictionary normally and upon failure, we retry using the non-compliant decoder.
use s9e\Bencode\Bencode; $input = 'd3:fooi42e3:bar4:spame'; try { $value = Bencode::decode($input); } catch (s9e\Bencode\Exceptions\ComplianceError $e) { echo 'Failed: ', $e->getMessage(), "\nRetry with non-compliant decoder:\n"; $value = Bencode::decodeNonCompliant($input); print_r($value); }
Failed: Out of order dictionary entry 'bar' at offset 10
Retry with non-compliant decoder:
ArrayObject Object
(
[storage:ArrayObject:private] => Array
(
[bar] => spam
[foo] => 42
)
)
Implementation details
- Rejects invalid bencoded data with meaningful exception messages.
- Uses ArrayObject instances to represent dictionaries. Dictionaries can be created and read using either the array notation or the object notation.
- Integers are limited in range from
PHP_INT_MIN
toPHP_INT_MAX
. - The encoder accepts booleans but converts them to integers.
- The encoder accepts floats that are equal to their integer value.