Threepio Laravel Package

Getting Started

This package is undocumented and unproven (0 stars, 0 dependents, no public issue history), so the first step is not reading a README — it's reading the repository. Treat marque/threepio as a set of protocol primitives you wire up yourself rather than a batteries-included client.

composer require marque/threepio

Then, in order:

1. composer.json — check the require block. If it declares illuminate/support you're dealing with a Laravel-aware package that likely ships a service provider; if not, it's framework-agnostic and you'll instantiate classes directly. Also check the autoload PSR-4 map so you know the namespace root before you start guessing at class names.
2. src/ — for a "BitTorrent protocol primitives" package, expect the surface area to cover: bencode encode/decode, the metainfo (.torrent) model, SHA-1 infohash computation, piece hashing, and the peer-wire message format. Identify which of these actually exist before designing around them.
3. tests/ — if there are fixtures, they are your best documentation. A tests/fixtures/*.torrent plus an expected-infohash assertion tells you more about intended usage than any prose could.
4. config/ — if a config file is published, it will reveal extension points (codec implementation, timeout values, tracker user-agent). If there's no config directory, assume no container bindings and no facades.

First use case: parsing an uploaded .torrent file and deriving its infohash, because that is the smallest end-to-end slice that exercises the bencode codec and the metainfo model together.

use Marque\Threepio\Bencode;          // verify actual namespace from src/
use Marque\Threepio\Metainfo;

$raw      = Storage::disk('torrents')->get("uploads/{$id}.torrent");
$decoded  = Bencode::decode($raw);
$meta     = Metainfo::fromArray($decoded);

$infohash = $meta->infohash();        // 20-byte SHA-1, hex or raw depending on API
$magnet   = "magnet:?xt=urn:btih:{$infohash}&dn=" . urlencode($meta->name());

If those class names don't exist, the pattern still holds — map the equivalents and move on. Do not build a queue worker or a tracker client on day one; confirm you can round-trip bencode and reproduce a known infohash first.

Implementation Patterns

Bencode as a boundary type. Bencode is not JSON — it has integer, byte-string, list, and dictionary types, and dictionaries are ordered. Keep the codec at the edge of your application: decode incoming .torrent bytes into plain PHP arrays, hand those to your own domain objects, and re-encode only when you must emit a .torrent. Do not let bencode arrays leak into controllers or models.

Metainfo → infohash → magnet, in that order. The typical pipeline is: store the raw torrent bytes, decode them, extract the info dictionary, SHA-1 the re-encoded info dictionary (see gotchas), and persist the resulting 20-byte hash as a binary column with a unique index. The infohash is your natural key for deduplication — two uploads of the same content must collapse to one row.

Piece verification in a queued job. Piece hashing is CPU-bound and belongs in a job, not a request. The pattern is: stream the file from a Laravel disk in piece_length-sized chunks, SHA-1 each chunk, compare against the pieces concatenated hash string from the metainfo. Use fopen/fread on the storage stream rather than get() so you never load a multi-gigabyte file into memory.

Bus::dispatch(new VerifyPieces($torrentId));

Peer-wire messages as value objects. If the package exposes message encode/decode, wrap it in a small transport class of your own (TorrentPeer, Handshake, Request) so the package's API doesn't spread through your codebase. Swap it for your own implementation later without touching call sites. Integration tip: keep the handshake and the choke/interest state machine in separate classes — mixing them is where most homegrown BitTorrent code rots.

Tracker announces sit outside this package. "Primitives" almost certainly means the package stops at the wire format and leaves HTTP/UDP tracker communication to you. Use Laravel's Http client for HTTP announces, and treat the compact peer list (peers as a 6-bytes-per-peer binary string) as another decode step you own.

Testing. Commit two or three small real .torrent files as fixtures and assert exact infohashes — that is your regression net. Use Http::fake() for tracker responses. If the package has no tests of its own, write yours before you write features; you are the maintainer of last resort here.

Blade/UI integration. Expose only the derived values — name, total size, piece count, infohash, magnet link — never the raw bencode. Compute size by summing the length fields of files or reading length for single-file torrents; both shapes occur and the model should normalise them.

Gotchas and Tips

The infohash must be computed over the original bytes. This is the single most common bug. SHA-1 the raw substring of the info dictionary as it appeared in the uploaded file, not a re-serialized version of your decoded array. PHP associative arrays do not preserve bencode's required key ordering in a way you can rely on, and any key-order change produces a different hash and a torrent that no client will accept. Extract the slice before decoding, or verify the codec preserves ordering.

Bencode strings are byte strings, not UTF-8. Never run mb_*, strtolower, or json_encode over decoded values. If you store the infohash in MySQL, use a BINARY(20) or VARBINARY(20) column — a VARCHAR with a collation will silently mangle or case-fold it. Same for the pieces field: hash concat, not text.

Zero dependents means zero Stack Overflow answers. Pin the exact version in composer.json ("marque/threepio": "1.0.*" or a commit hash) and vendor-lock it. There is no upgrade path, no security advisory feed, and no one to ask. Before adopting, read the source for eval, exec, unserialize, and raw socket calls — you are trusting it with untrusted input from the public internet.

Malformed torrents are the attack surface. Every field from an uploaded .torrent is attacker-controlled. Guard against: piece_length that is absurdly large or zero, pieces whose length isn't a multiple of 20, files arrays with .. in the path, negative length, and deeply nested bencode lists (stack exhaustion). Write a validation layer in front of the codec and fail closed.

Memory and piece count. A 20 GB torrent with 256 KiB pieces yields ~80,000 hashes; the pieces string alone is 1.6 MB. Fine, but do not hold the whole file and all computed hashes in memory simultaneously. Iterate.

Config quirks. If there is a service provider but no config/threepio.php, the package is probably using hardcoded defaults or env() calls — grep for env( in src/. env() returning null inside a cached config is a classic production-only failure; replace with config() entries you own.

Debugging. When an infohash is wrong, hexdump the raw info slice and compare against aria2c --show-files or transmission-show output. That single comparison resolves ordering, encoding, and hashing questions at once.

Extension points. The realistic ones are the codec and the transport: if the package defines an interface for either, bind your own implementation in a service provider rather than subclassing a concrete class. If it does not, wrap it — the package is unmaintained by any observable metric, and a thin adapter layer is your insurance policy.