Phoenix v.3.1.5

A lightweight BitTorrent Tracker written in PHP, with an SQL backend, for people that just want to host a tracker, not the torrent listing site.

Installation

What Do You Need?

Required

• PHP >= 8.2 with the mysqli and xml extensions. The bundled date, filter, json, pcre, and session extensions are also used (these ship enabled by default).
• A PHP-compatible web server (Apache or Nginx).
• A MySQL-compatible database.

Recommended

• The latest supported version of PHP
• The latest version of Nginx (>= 1.18 with HTTP/2) or Apache 2.4.
• The latest version of MariaDB.

Install Guide

1. Copy config/phoenix.default.php to config/phoenix.custom.php
2. Edit the variables in config/phoenix.custom.php
3. Upload Phoenix to your server.
4. Point your web server's document root at the public/ directory. Only public/ should be web-reachable; src/, bin/, config/, and tests/ must remain outside the document root so configuration (including database credentials) is never served. See APACHE.md or NGINX.md for example configurations.
5. Load admin.php in your browser and run the Setup option.
6. After setup, move public/admin.php into src/ (mv public/admin.php src/admin.php) so it stops being web-reachable. Move it back temporarily if you ever need to re-run setup.

Project Structure

Phoenix follows an MVC-inspired structure optimized for procedural PHP:

phoenix/
├── public/              # Web-accessible entry points (controllers)
│   ├── announce.php     # BitTorrent announce endpoint (BEP 3)
│   ├── scrape.php       # BitTorrent scrape endpoint (BEP 15)
│   ├── index.php        # Public torrent listing (optional)
│   ├── admin.php        # Admin panel & installer
│   └── magnet.php       # Client-side magnet link generator
├── src/
│   ├── phoenix.php      # Bootstrap: loads config, connects to DB
│   ├── functions/       # Business logic helpers (one function per file)
│   ├── model/           # Database operations (one query function per file)
│   ├── views/           # Presentation layer (bencode, XML, HTML)
│   └── hooks/           # User-defined lifecycle hooks (optional)
├── config/
│   ├── phoenix.default.php    # Default configuration (DO NOT EDIT)
│   └── phoenix.custom.php     # Your configuration (gitignored)
├── bin/                 # Cron maintenance scripts
│   ├── backup-database.php
│   └── clean-and-optimize.php
└── tests/               # PHPUnit test suite

Architecture Notes

• Controllers (public/*.php) are thin orchestrators: sanitize input → call model → call view.
• Models (src/model/*.php) handle all database operations. Each file exports one function that accepts $connection, $settings, and domain parameters.
• Views (src/views/*.php) handle presentation. Bencode for BitTorrent protocol, HTML for humans, XML/JSON for debugging.
• Functions (src/functions/*.php) contain business logic helpers that don't fit cleanly into model or view (sanitization, validation, address parsing, etc.).
• Hooks (src/hooks/*.php) are optional operator-defined scripts called at lifecycle points (peer.new, peer.stopped, download.complete, etc.). Keep them empty in this repo.

Configuration

Configuration should take place in config/phoenix.custom.php, NOT config/phoenix.default.php. Phoenix will attempt to use the default configuration if yours is missing.

Server Configuration

Phoenix ships with example web server configurations covering document root, .php extension stripping, and admin endpoint rate limiting:

• APACHE.md
• NGINX.md

Cron (Automating Maintenance)

1. Edit config/phoenix.custom.php and set:
   • $settings['backup_dir'] to change the backup directory. Defaults to backups.
   • $settings['clean_with_cron'] to true to enable the script and disable occaisional cleanup on announce.
2. Edit your crontab with crontab -e, and add a crontab like the following. You can edit the times, and should make sure the paths are correct by running the commands after the asterisks.

15 * * * * php ~/phoenix/bin/clean-and-optimize.php
30 * * * * php ~/phoenix/bin/backup-database.php