orpheusnet/bencode-torrent

PHP Library for decoding and encoding BitTorrent BEncoded data, built for Gazelle

v1.3.0 2023-10-13 00:09 UTC

Requires

• php: >=8.1
• ext-mbstring: *

Requires (Dev)

• phpstan/phpstan: ^1.10.38
• phpunit/phpunit: ^10.4.1
• squizlabs/php_codesniffer: ^3.7.2

Unlicense

• Orpheus

README

PHP library for encoding and decoding BitTorrent BEncode data, focused around usage within Gazelle.

Usage

composer require orpheusnet/bencode-torrent

require('vendor/autoload.php');
$bencode = new \OrpheusNET\BencodeTorrent\BencodeTorrent();
$bencode->decodeFile('path/to/file.torrent');
var_dump($bencode->getName());
var_dump($bencode->getHexInfoHash());
var_dump($bencode->getFileList());

See the BencodeTorrent class for more information on the available methods. Additionally, see Bencode for the underlying library to encode/decode BEncode data.

Description

BEncode is the encoding used by BitTorrent to store and transmitting loosely structured data. It supports:

• byte strings
• integers
• lists
• dictionaries (associative arrays, where keys are sorted alphabetically)

You can see more information about how these types are supported at BitTorrentSpecification#Bencoding.

In addition to the above, torrent files are expected to be BEncoded dictionaries that contain minimally the keys announce (byte string) and info (dictionary). Within the info dictionary, we then expect piece length (integer) and pieces (byte string). If the torrent has only a single file, we then expect name (byte string) and length (integer), whereas for a multi-file torrent, we'll have name (byte string) and files (list) where each element is a dictionary that has the keys length (integer) and path (list of strings).

As such, this library will make some checks when loading data that these mandatory fields exist or else an Exception is raised. More information on these fields can be found at BitTorrentSpecification#Metainfo_File_Structure.

Finally, this library is primarily aimed at being used within the Gazelle so we have some utility functions within the library that make sense there to accomplish the following things:

• Ensuring torrent files are marked as 'private'
• Setting a 'source' on torrents (to ensure unique info hash)
• Cleaning out unnecessary fields that also reveal stuff about a user (like announce list and created by)
• Generate string file lists as expected by Gazelle for display

This is based (loosely) off the code in the two separate BEncode libraries within WCD's Gazelle (bencodetorrent.class.php and torrent.class.php), but without the now unnecessary 32bit shims as well as making it a unified library used for both uploading and downloading the torrent files.