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, and string values are encoded natively.
float values that can be losslessly converted to integers are coerced to int.
bool values are coerced to int.
An object that implements s9e\Bencode\BencodeSerializable is encoded as the value returned by its bencodeSerialize() 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 0s 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 to PHP_INT_MAX.
The encoder accepts booleans but converts them to integers.
The encoder accepts floats that are equal to their integer value.

s9e / bencode

Maintainers

Details