Download the PHP package marque/trove without Composer

Marque Trove

Core models, services, and contracts for the Marque tracker platform.

Starting from scratch?

Trove is the catalogue core — models, roles, policies. On its own it tracks nothing and serves no pages. Pick the shape you're building:

Each resolves its own supporting packages (threepio for the BitTorrent protocol, deck for the UI shell).

Installation

Publish the config and run migrations:

What's Included

• Torrent model - info_hash, metadata, file storage
• TorrentService - CRUD, .torrent file upload/parsing, search
• Role system - User, Uploader, Moderator, Admin hierarchy
• Tracker stats contract - TrackerStatsInterface and the TrackerStats / TorrentStats value objects; a tracker package (bloodhound) implements it, issuing keys and tracking bytes
• Authorization - Policies for create, update, delete operations

User Model Setup

Add the Trove traits and interface to your User model:

marque:install does this for you — it shows the diff, backs the file up and applies it on confirmation. The manual version is here for anyone wiring the packages up by hand.

On a private tracker, add HasTrackerStats as well. It lives in marque/bloodhound, not trove:

A public tracker does not install bloodhound, so adding that trait there fatals on a missing class.

HasRoles gives you role checks:

HasTrackerStats issues each new user an announce key (on email verification, when the app verifies addresses) and gives the model a few formatting helpers (getRatioForHumans(), getUploadedForHumans(), …).

To read tracker figures or a user's announce key from your own code, ask the tracker rather than the User model. trove declares the contract; bloodhound implements it; nothing binds it on an install without a tracker:

statsForTorrent($user, $torrent) returns a TorrentStats for one torrent, including when the user first and last completed it. Every figure is a raw integer (bytes, seconds) — formatting is yours.

⚠️ $user->announce_key is not the user's key as of bloodhound 6. Keys live in bloodhound's own announce_keys table; the old users.announce_key column is left in place but never read or written. Use announceKeyFor().

Working with Torrents

Uploads and downloads: what the tracker decides

trove stores the uploader's original .torrent, and never modifies its info dictionary: the info_hash is sha1 of those raw bytes, and every member's download carries them unchanged, so everyone shares one hash. What the file must be, and what goes into a download, is the installed tracker's call. It binds TorrentFilePolicyInterface: bloodhound and hound both do. TorrentFileService applies it:

On upload, inspect() refuses a file that isn't a valid torrent and a BitTorrent v2-only torrent (it has no v1 info_hash), warns about a hybrid, and applies the tracker's PrivateFlag rule. createFromUpload() runs the same check and throws TorrentRefused before storing anything. A refused upload is never rewritten: the flag is inside the info dictionary, so changing it would change the hash under the uploader. The refusal tells them to recreate the torrent with "private" ticked or unticked.

On download, forDownload() keeps only info (and encoding) from the stored file, byte for byte. It sets announce to the tracker's URL for this user, and comment to the page you pass. Everything else the uploader's client wrote is dropped. That includes announce-list: clients prefer it over announce, and an uploader's list can carry their personal announce URL for another site. Cross-seeding is a separate package (#10950). When the tracker has no URL for this user (a private tracker's member with no key yet), forDownload() throws NoAnnounceUrl; never serve a file without one. With no tracker installed, the stored file is served as it is.

Checking stored info hashes

Before trove 4.4, uploads were hashed from the decoded-and-re-encoded info dictionary. A torrent whose info wasn't canonical bencode was stored under a hash no client announces, and never saw a peer. To find any such torrents:

It re-hashes each stored .torrent the way clients do, lists every torrent whose stored info_hash differs (with both hashes), and exits non-zero if it finds any. A torrent whose file is missing, isn't valid bencode or has no info dictionary (missing, or not a dictionary) is listed as a warning and skipped, and doesn't affect the exit code. It changes nothing. The correct hash may already belong to another row, and anything keyed on the old one needs thought, so fixing them is your call.

Dashboard panels

The user dashboard (/dashboard, rendered by marque/usarrs) shows whatever panels packages have registered. It names no package and holds no list of its own, so a package Marque has never heard of gets a panel exactly as a first-party one does — same card, same heading, ordered among the others by the position it chose.

A panel is a Livewire component you own plus a declaration in trove's registry. Register from your own service provider's boot(), with a dependency on marque/trove alone:

DashboardPanel::forRole('acme-mod', 'Moderation', 'acme-mod-panel', Role::Moderator) is the shorthand for a role gate, with the same semantics as NavItem::forRole() — a guest never clears it.

Nothing depends on the dashboard in order to contribute to it. Registering a panel needs trove and nothing else; if usarrs is not installed the declaration simply goes unread. Your package boots and behaves identically either way.

Three separate things decide whether a panel appears, and they belong in different places:

usarrs's own panels sit at positions 10 (tracker stats), 20 (announce key), 30 (account security) and 40 (invites), so pick a position between them to interleave. Panels are ordered by position, then label. Registering a duplicate identifier throws rather than silently replacing the existing panel.

This is public API. DashboardPanel and DashboardPanelRegistry — their constructor parameters and public methods — follow trove's semver from 4.3, alongside the nav and admin-screen registries (see VERSIONING.md). The dashboard page that renders them, and usarrs's own panels on it, version with usarrs.

Configuration

Published to config/trove.php:

Ratio enforcement isn't configured here. It belongs to the tracker, and bloodhound's ratio_mode / min_ratio / min_seedtime keys are planned and not enforced yet (#10732).

Migrations

Trove creates:

• torrents table (info_hash, name, description, size, file_count, torrent_file, user_id, min_role, seeders, leechers, times_completed)
• Adds a role column to the users table

That is all trove adds to users. The tracker columns (uploaded, downloaded, seedtime) come from bloodhound's migrations, and announce keys live in bloodhound's own announce_keys table.

Publish migrations to customise them:

Roles

Four roles with a strict hierarchy:

Authorization

Trove registers a TorrentPolicy:

• View - Everyone, unless the torrent sets min_role (see below)
• Create - Uploader role or above
• Update - Torrent owner, or Moderator+
• Delete - Moderator or above

Restricting a torrent to a role

Set min_role to hide a torrent from users below that role. Null — the default — means everyone can see it.

Because roles are ranked, restricting to Uploader also admits moderators and admins. The torrent's own uploader is not exempt: an uploader demoted below the torrent's min_role loses access to it.

Enforcement happens in two places, and both matter:

• TorrentPolicy::view() covers detail pages and .torrent downloads. The download is gated exactly as tightly as viewing, because on a private tracker it carries the member's announce key (see "Uploads and downloads" above).
• Torrent::scopeVisibleTo($user) covers listings. A policy guards a single record; without the scope, restricted torrents would still appear in every index, API collection and count. TorrentService's list() and find() apply it for you; findByInfoHash() deliberately does not.

Passing no viewer resolves to the authenticated user. That is deliberate — an omitted argument must not be mistaken for "an unauthenticated visitor", or a caller that forgets it quietly gets the wrong list.

Dead torrents

seeders and leechers are kept on the torrent by the tracker packages as a queryable projection of live peer state (which lives in Redis, where SQL cannot filter or sort on it).

Set hide_dead_torrents to true to drop seederless torrents from listings; $service->list(includeDead: true) overrides it. It is off by default because a torrent has no seeders until its first announce — enabling it on a catalogue that has not announced yet hides everything in it.

Requirements

• PHP 8.3+
• Laravel 13+

License

MIT. See LICENSE.