### User Model Query Example in PHP

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Example of querying a user with counts of related torrents and eager loading of other relationships.

```php
// 关联查询
$user = User::query()
    ->withCount(['torrents', 'seeding_torrents', 'leeching_torrents'])
    ->with(['medals', 'exams'])
    ->find($userId);
```

--------------------------------

### Torrent Model Query Example in PHP

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Example of querying torrents with eager loading of relationships and pagination.

```php
// 关联查询示例
$torrent = Torrent::query()
    ->with(['user', 'basic_category', 'tags', 'peers', 'snatches'])
    ->where('visible', 'yes')
    ->where('banned', 'no')
    ->orderBy('id', 'desc')
    ->paginate(25);
```

--------------------------------

### Docker Compose Configuration for NexusPHP

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Example docker-compose.yml file for deploying NexusPHP with MySQL and Redis.

```yaml
version: '3'
services:
  app:
    build:
      context: .docker/php
      dockerfile: Dockerfile
    volumes:
      - .:/var/www/html
    depends_on:
      - mysql
      - redis

  web:
    build:
      context: .docker/openresty
      dockerfile: Dockerfile
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - app

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: nexusphp
      MYSQL_ROOT_PASSWORD: your_password

  redis:
    image: redis:alpine
```

--------------------------------

### Get Upload Section Configurations

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Retrieves the available categories and taxonomies (like source, codec, standard) for torrent uploads. This data is useful for populating upload forms. Requires API token authentication.

```http
// GET /api/sections
// Headers: Authorization: Bearer {token}

// Response
{
    "ret": 0,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "Movies",
            "categories": [
                {"id": 1, "name": "电影"},
                {"id": 2, "name": "纪录片"}
            ],
            "taxonomies": {
                "source": [{"id": 1, "name": "BluRay"}],
                "codec": [{"id": 1, "name": "x264"}],
                "standard": [{"id": 1, "name": "1080p"}]
            }
        }
    ]
}
```

--------------------------------

### Get User Profile

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Retrieve detailed user information, including upload/download stats, seed bonus, and level. Pass a user ID to get a specific profile, or omit it to get the current logged-in user's profile. Requires an Authorization header.

```http
// GET /api/profile/{id?}
// Headers: Authorization: Bearer {token}
// 不传id则获取当前登录用户信息
```

```bash
// curl 示例
curl -X GET "https://your-site.com/api/profile/1" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"
```

```json
// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 1,
        "username": "example_user",
        "email": "user@example.com",
        "class": 3,
        "class_text": "Elite User",
        "uploaded": 107374182400,
        "downloaded": 53687091200,
        "seedbonus": 12500.50,
        "seed_points": 85000,
        "invites": 5,
        "added": "2023-01-01 00:00:00",
        "last_login": "2024-01-20 15:30:00"
    }
}
```

--------------------------------

### Get Torrent Comments

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Retrieve a list of comments for a specific torrent. Requires an Authorization header and a torrent_id in the query parameters.

```http
// GET /api/comments?filter[torrent_id]=123
// Headers: Authorization: Bearer {token}
```

```json
// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "id": 1,
                "text": "感谢分享!",
                "user": {
                    "id": 2,
                    "username": "commenter"
                },
                "added": "2024-01-16 12:00:00"
            }
        ]
    }
}
```

--------------------------------

### Initialize Layer with a Welcome Page

Source: https://github.com/xiaomlove/nexusphp/blob/php8/public/vendor/layer-v3.5.1/test.html

This snippet demonstrates how to open a Layer pop-up that loads an external HTML page. It's configured to be resizable and includes a callback function that executes when the pop-up is closed.

```javascript
;!function(){ //页面一打开就执行，放入ready是为了layer所需配件（css、扩展模块）加载完毕 layer.ready(function(){ layer.open({ type: 2, title: '欢迎页', maxmin: true, area: ['800px', '500px'], content: 'http://layer.layui.com/test/welcome.html', end: function(){ layer.tips('Hi', '#about', {tips: 1}) } }); }); //关于 $('#about').on('click', function(){ layer.alert('layui 出品'); }); }();
```

--------------------------------

### Database Backup Commands

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Execute backups for the database and website files. Options include backing up only the database, only the web files, or both. A cronjob command is also available.

```bash
# 备份数据库
php artisan backup:database
```

```bash
# 备份网站文件
php artisan backup:web
```

```bash
# 全部备份
php artisan backup:all
```

```bash
# 定时备份任务
php artisan backup:cronjob
```

--------------------------------

### Environment Configuration

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Details on environment variable configuration using the .env file.

```APIDOC
## .env File Configuration

### Description
NexusPHP uses a `.env` file for environment-specific configurations.

### Database Configuration
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nexusphp
DB_USERNAME=root
DB_PASSWORD=your_password
```

### Redis Configuration
```env
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
```

### Elasticsearch Configuration (Optional)
```env
ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_SCHEME=https
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASS=your_password
```
```

--------------------------------

### Add Torrent Bookmark

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Use this endpoint to add a torrent to the user's bookmark list. Requires an Authorization header with a Bearer token.

```http
// 添加收藏
// POST /api/bookmarks
// Headers: Authorization: Bearer {token}
{
    "torrent_id": 123
}
```

```bash
// curl 示例
curl -X POST "https://your-site.com/api/bookmarks" \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"torrent_id": 123}'
```

```json
// Response
{
    "ret": 0,
    "msg": "收藏成功",
    "data": {
        "id": 1,
        "torrentid": 123,
        "userid": 1
    }
}
```

--------------------------------

### Calculate Seeding Bonus

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Calculate seeding bonus and magic points for a specified user. Requires the user ID as an argument.

```bash
# 计算单个用户的做种积分
php artisan tracker:calculate_seed_bonus {uid}
```

```bash
# 示例
php artisan tracker:calculate_seed_bonus 1
```

--------------------------------

### Plugin Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manage NexusPHP's plugin system. Commands are available for various plugin actions and cronjob tasks.

```bash
# 插件相关操作
php artisan plugin {action}
```

```bash
# 插件定时任务
php artisan plugin:cronjob
```

--------------------------------

### Retrieve Torrent List with Filters and Sorting

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Fetches a list of torrents, supporting filtering by title, category, visibility, and bookmark status, as well as sorting and including related user data. Requires 'torrent:list' permission.

```http
// GET /api/torrents/{section?}
// Headers: Authorization: Bearer {token}

// 请求参数示例
// filter[title]=keyword        - 按标题搜索
// filter[category]=1           - 按分类筛选
// filter[visible]=1            - 可见性筛选 (0=全部, 1=可见, 2=不可见)
// filter[bookmark]=include     - 收藏筛选 (include/exclude)
// sort=-id                     - 按ID倒序排列
// include=user,tags            - 包含关联数据
// fields=has_bookmarked,download_url - 包含额外字段

// curl 示例
curl -X GET "https://your-site.com/api/torrents?filter[title]=movie&sort=-id&include=user" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "id": 123,
                "name": "Example.Movie.2024.1080p.BluRay",
                "small_descr": "优质蓝光资源",
                "size": 8589934592,
                "seeders": 50,
                "leechers": 10,
                "times_completed": 200,
                "added": "2024-01-15 10:30:00",
                "sp_state": 2,
                "category": {
                    "id": 1,
                    "name": "Movies"
                }
            }
        ],
        "links": {...},
        "meta": {"current_page": 1, "total": 100}
    }
}
```

--------------------------------

### Environment Configuration

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

NexusPHP uses a .env file for environment configuration. This includes settings for database, Redis, and optional Elasticsearch connection.

```env
# 数据库配置
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nexusphp
DB_USERNAME=root
DB_PASSWORD=your_password

# Redis 配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0

# Elasticsearch 配置 (可选)
ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_SCHEME=https
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASS=your_password
```

--------------------------------

### Exam System Commands

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manage user exam assignments and progress checks. Includes commands for assigning exams, checking results, and updating progress.

```bash
# 分配考核给符合条件的用户
php artisan exam:assign
```

```bash
# 定时任务分配考核
php artisan exam:assign_cronjob
```

```bash
# 检查考核结果
php artisan exam:checkout_cronjob
```

```bash
# 更新考核进度
php artisan exam:update_progress
```

--------------------------------

### Run NexusPHP Docker Container

Source: https://github.com/xiaomlove/nexusphp/blob/php8/README.md

This command pulls the latest NexusPHP Docker image and runs it as a container. Ensure the DOMAIN is set correctly and the port is accessible. Adjust the port mapping if the local 80 port is already in use.

```bash
docker pull xiaomlove/nexusphp:latest
docker run --name my-nexusphp -e DOMAIN=xxx.com -p 80:80 xiaomlove/nexusphp:latest
```

--------------------------------

### Site Configuration API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Retrieve site configuration, such as available torrent sections and categories.

```APIDOC
## GET /api/sections

### Description
Retrieves the available torrent sections and their associated categories and taxonomies. This is useful for populating upload forms.

### Method
GET

### Endpoint
/api/sections

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -X GET "https://your-site.com/api/sections" \
  -H "Authorization: Bearer your_api_token"
```

### Response
#### Success Response (200)
- **ret** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (array) - List of sections.
  - **id** (integer) - Section ID.
  - **name** (string) - Section name.
  - **categories** (array) - List of categories within the section.
    - **id** (integer) - Category ID.
    - **name** (string) - Category name.
  - **taxonomies** (object) - Taxonomy options for the section.
    - **source** (array) - List of source options.
      - **id** (integer) - Option ID.
      - **name** (string) - Option name.
    - **codec** (array) - List of codec options.
      - **id** (integer) - Option ID.
      - **name** (string) - Option name.
    - **standard** (array) - List of standard options.
      - **id** (integer) - Option ID.
      - **name** (string) - Option name.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "Movies",
            "categories": [
                {"id": 1, "name": "电影"},
                {"id": 2, "name": "纪录片"}
            ],
            "taxonomies": {
                "source": [{"id": 1, "name": "BluRay"}],
                "codec": [{"id": 1, "name": "x264"}],
                "standard": [{"id": 1, "name": "1080p"}]
            }
        }
    ]
}
```
```

--------------------------------

### Artisan: Cleanup Tasks

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Triggers asynchronous cleanup tasks such as seed bonus calculation, seeding time updates, and torrent statistics.

```APIDOC
## php artisan cleanup

### Description
Executes various cleanup and maintenance tasks.

### Usage
```bash
# Calculate seed bonus for a range of users
php artisan cleanup --action=seed_bonus --begin_id=1 --end_id=100

# Update seeding/leeching times for a range of users
php artisan cleanup --action=seeding_leeching_time --begin_id=1 --end_id=100

# Update seeder counts for torrents
php artisan cleanup --action=seeders_etc --begin_id=1 --end_id=100

# Process user IDs stored in a Redis key
php artisan cleanup --action=seed_bonus --id_redis_key=user_ids_to_process
```
```

--------------------------------

### User Authentication and Token Generation

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Use this endpoint to authenticate users via username and password and obtain an API access token. The token is required for subsequent authenticated API requests. Optionally, request site information.

```json
// POST /api/login
// Request
{
    "username": "your_username",
    "password": "your_password",
    "include": "site_info"  // 可选,返回站点信息
}

// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "user": {
            "id": 1,
            "username": "your_username",
            "email": "user@example.com",
            "class": 1,
            "uploaded": 1073741824,
            "downloaded": 536870912
        },
        "token": "1|abcdefghijklmnopqrstuvwxyz123456",
        "site_info": {
            "site_name": "My PT Site"
        }
    }
}
```

--------------------------------

### Artisan: Database Backup

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Performs backups of the database and website files.

```APIDOC
## php artisan backup.*

### Description
Commands for managing database and file backups.

### Usage
```bash
# Backup the database
php artisan backup:database

# Backup website files
php artisan backup:web

# Perform a full backup (database and files)
php artisan backup:all

# Run the backup task via cron job
php artisan backup:cronjob
```
```

--------------------------------

### Torrent Model Status Constants in PHP

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Defines constants for torrent status, promotion types, and visibility.

```php
// 种子状态常量
Torrent::PROMOTION_NORMAL = 1;      // 普通
Torrent::PROMOTION_FREE = 2;         // 免费
Torrent::PROMOTION_TWO_TIMES_UP = 3; // 双倍上传
Torrent::PROMOTION_FREE_TWO_TIMES_UP = 4; // 免费+双倍上传

// 置顶状态
Torrent::POS_STATE_STICKY_NONE = 'normal';
Torrent::POS_STATE_STICKY_FIRST = 'sticky';
Torrent::POS_STATE_STICKY_SECOND = 'r_sticky';

// 审核状态
Torrent::APPROVAL_STATUS_NONE = 0;   // 待审核
Torrent::APPROVAL_STATUS_ALLOW = 1;  // 通过
Torrent::APPROVAL_STATUS_DENY = 2;   // 拒绝
```

--------------------------------

### MeiliSearch Index Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manage MeiliSearch search engine. Commands are available for importing data and viewing statistics.

```bash
# 导入数据到 MeiliSearch
php artisan meilisearch:import
```

```bash
# 查看统计信息
php artisan meilisearch:stats
```

--------------------------------

### User Model Level Constants in PHP

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Defines constants for various user levels within the system.

```php
// 用户等级常量
User::CLASS_PEASANT = 0;        // Peasant
User::CLASS_USER = 1;           // User
User::CLASS_POWER_USER = 2;     // Power User
User::CLASS_ELITE_USER = 3;     // Elite User
User::CLASS_VIP = 10;           // VIP
User::CLASS_MODERATOR = 13;     // Moderator
User::CLASS_ADMINISTRATOR = 14; // Administrator
User::CLASS_SYSOP = 15;         // Sysop
```

--------------------------------

### Upload New Torrent

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Allows uploading a new torrent file to the site. Requires 'torrent:upload' permission. Essential parameters include the torrent file, name, description, and category ID. Optional parameters include subtitle, IMDB URL, and anonymous upload flag.

```http
// POST /api/upload
// Headers: Authorization: Bearer {token}
// Content-Type: multipart/form-data

// 请求参数
// file: torrent文件 (必需)
// name: 种子标题 (必需)
// descr: 种子描述 (必需)
// type: 分类ID (必需)
// small_descr: 副标题 (可选)
// url: IMDB链接 (可选)
// uplver: 'yes'表示匿名上传 (可选)

// curl 示例
curl -X POST "https://your-site.com/api/upload" \
  -H "Authorization: Bearer your_api_token" \
  -F "file=@/path/to/movie.torrent" \
  -F "name=Example.Movie.2024.1080p.BluRay" \
  -F "descr=这是一部优秀的电影资源..." \
  -F "type=1" \
  -F "small_descr=优质蓝光" \
  -F "url=https://www.imdb.com/title/tt1234567"

// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 456
    }
}
```

--------------------------------

### User Bookmarks API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manage user's torrent bookmarks, including adding and deleting.

```APIDOC
## POST /api/bookmarks

### Description
Adds a torrent to the user's bookmark list.

### Method
POST

### Endpoint
/api/bookmarks

### Parameters
#### Request Body
- **torrent_id** (integer) - Required - The ID of the torrent to bookmark.

### Request Example
```json
{
    "torrent_id": 123
}
```

### Response
#### Success Response (200)
- **ret** (integer) - Return code, 0 for success.
- **msg** (string) - Success or error message.
- **data** (object) - Contains bookmark details.
  - **id** (integer) - The ID of the bookmark.
  - **torrentid** (integer) - The ID of the bookmarked torrent.
  - **userid** (integer) - The ID of the user who bookmarked.

#### Response Example
```json
{
    "ret": 0,
    "msg": "收藏成功",
    "data": {
        "id": 1,
        "torrentid": 123,
        "userid": 1
    }
}
```

## POST /api/bookmarks/delete

### Description
Deletes a torrent from the user's bookmark list.

### Method
POST

### Endpoint
/api/bookmarks/delete

### Parameters
#### Request Body
- **torrent_id** (integer) - Required - The ID of the torrent to remove from bookmarks.

### Request Example
```json
{
    "torrent_id": 123
}
```
```

--------------------------------

### Artisan: Seed Bonus Calculation

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Calculates seed bonus and magic points for specified users.

```APIDOC
## php artisan tracker:calculate_seed_bonus {uid}

### Description
Calculates seed bonus and magic points for a given user.

### Usage
```bash
# Calculate for a single user
php artisan tracker:calculate_seed_bonus {uid}

# Example
php artisan tracker:calculate_seed_bonus 1
```
```

--------------------------------

### Artisan: Examination System Commands

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manages user examination assignments and progress tracking.

```APIDOC
## php artisan exam.*

### Description
Commands for managing the user examination system.

### Usage
```bash
# Assign examinations to eligible users
php artisan exam:assign

# Assign examinations via cron job
php artisan exam:assign_cronjob

# Check examination results via cron job
php artisan exam:checkout_cronjob

# Update examination progress
php artisan exam:update_progress
```
```

--------------------------------

### Artisan: System Update

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Executes NexusPHP system updates, including database migrations and configuration changes.

```APIDOC
## php artisan nexus:update

### Description
Performs system updates for NexusPHP.

### Usage
```bash
# Basic update
php artisan nexus:update

# Update to a specific version
php artisan nexus:update --tag=1.8.0

# Update from the development branch
php artisan nexus:update --tag=dev --branch=php8

# Keep temporary files after update
php artisan nexus:update --tag=1.8.0 --keep_tmp

# Include composer dependency updates
php artisan nexus:update --tag=1.8.0 --include_composer
```
```

--------------------------------

### System Update Command

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Execute NexusPHP system updates, including database migrations and configuration updates. Various options are available for specifying tags, branches, and including composer dependencies.

```bash
# 基本更新
php artisan nexus:update
```

```bash
# 指定版本更新
php artisan nexus:update --tag=1.8.0
```

```bash
# 从开发分支更新
php artisan nexus:update --tag=dev --branch=php8
```

```bash
# 保留临时文件
php artisan nexus:update --tag=1.8.0 --keep_tmp
```

```bash
# 包含 composer 依赖更新
php artisan nexus:update --tag=1.8.0 --include_composer
```

--------------------------------

### Pieces Hash Query

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Query torrent information using the pieces hash of a torrent file, useful for seeding tools. Requires a passkey authentication header.

```http
// POST /pieces-hash
// Headers: Authorization: Bearer {passkey_auth}
{
    "pieces_hash": ["hash1", "hash2", "hash3"]
}
```

```json
// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "hash1": 123,
        "hash2": 456
    }
}
```

--------------------------------

### Retrieve Single Torrent Details

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Fetches detailed information for a specific torrent, including description, file list, and peer information. Supports including related data and specifying fields. Requires 'torrent:view' permission.

```http
// GET /api/detail/{id}
// Headers: Authorization: Bearer {token}

// 请求参数
// include=user,extra,tags      - 包含上传者、描述、标签
// fields=description,download_url,has_bookmarked - 包含描述和下载链接

// curl 示例
curl -X GET "https://your-site.com/api/detail/123?include=user,extra&fields=description,download_url" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

// Response
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 123,
        "name": "Example.Movie.2024.1080p.BluRay",
        "size": 8589934592,
        "numfiles": 5,
        "seeders": 50,
        "leechers": 10,
        "times_completed": 200,
        "description": "详细描述内容...",
        "download_url": "https://your-site.com/download.php?downhash=1.xxxxx",
        "user": {
            "id": 1,
            "username": "uploader"
        },
        "tags": [
            {"id": 1, "name": "BluRay", "color": "#0066cc"}
        ]
    }
}
```

--------------------------------

### Pieces Hash Query API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Query torrent information using pieces hash, useful for synchronization tools.

```APIDOC
## POST /pieces-hash

### Description
Queries torrent information based on provided pieces hashes.

### Method
POST

### Endpoint
/pieces-hash

### Parameters
#### Headers
- **Authorization** (string) - Required - Passkey authentication token.
#### Request Body
- **pieces_hash** (array) - Required - An array of pieces hash strings.

### Request Example
```json
{
    "pieces_hash": ["hash1", "hash2", "hash3"]
}
```

### Response
#### Success Response (200)
- **ret** (integer) - Return code, 0 for success.
- **msg** (string) - Success or error message.
- **data** (object) - Contains mapping of pieces hash to torrent IDs.
  - **hash1** (integer) - Example mapping of a pieces hash to a torrent ID.
  - **hash2** (integer) - Example mapping of another pieces hash to a torrent ID.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "hash1": 123,
        "hash2": 456
    }
}
```
```

--------------------------------

### Artisan: Plugin Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manages the NexusPHP plugin system.

```APIDOC
## php artisan plugin.*

### Description
Commands for managing NexusPHP plugins.

### Usage
```bash
# Perform plugin-related actions (e.g., enable, disable, install)
php artisan plugin {action}

# Run plugin cron jobs
php artisan plugin:cronjob
```
```

--------------------------------

### Elasticsearch Index Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manage Elasticsearch full-text search indexes. Commands are available for creating, deleting, importing data, and viewing index information.

```bash
# 创建索引
php artisan es:create_index
```

```bash
# 删除索引
php artisan es:delete_index
```

```bash
# 导入数据
php artisan es:import
```

```bash
# 查看信息
php artisan es:info
```

--------------------------------

### Cleanup Task Scheduling

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Trigger asynchronous cleanup tasks, including seeding bonus calculations, seeding/leeching time updates, and torrent seeder counts. Supports specifying ID ranges or using Redis keys for processing.

```bash
# 计算做种积分
php artisan cleanup --action=seed_bonus --begin_id=1 --end_id=100
```

```bash
# 更新做种/下载时间
php artisan cleanup --action=seeding_leeching_time --begin_id=1 --end_id=100
```

```bash
# 更新种子做种者数量
php artisan cleanup --action=seeders_etc --begin_id=1 --end_id=100
```

```bash
# 使用 Redis 键存储的 ID 列表
php artisan cleanup --action=seed_bonus --id_redis_key=user_ids_to_process
```

--------------------------------

### User Authentication API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Authenticate users with username and password to obtain an API access token. The token is used for subsequent API requests.

```APIDOC
## POST /api/login

### Description
Authenticate users with username and password to obtain an API access token. The token is used for subsequent API requests.

### Method
POST

### Endpoint
/api/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.
- **include** (string) - Optional - Include site information in the response.

### Request Example
```json
{
    "username": "your_username",
    "password": "your_password",
    "include": "site_info"
}
```

### Response
#### Success Response (200)
- **ret** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (object) - Contains user information and token.
  - **user** (object) - User details.
    - **id** (integer) - User ID.
    - **username** (string) - Username.
    - **email** (string) - User email.
    - **class** (integer) - User class level.
    - **uploaded** (integer) - Total uploaded bytes.
    - **downloaded** (integer) - Total downloaded bytes.
  - **token** (string) - API access token.
  - **site_info** (object) - Optional site information.
    - **site_name** (string) - Name of the site.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "user": {
            "id": 1,
            "username": "your_username",
            "email": "user@example.com",
            "class": 1,
            "uploaded": 1073741824,
            "downloaded": 536870912
        },
        "token": "1|abcdefghijklmnopqrstuvwxyz123456",
        "site_info": {
            "site_name": "My PT Site"
        }
    }
}
```
```

--------------------------------

### Third-Party Tool Authentication

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

API endpoints for authentication with third-party automation tools like NasTools, IYUU, and AMMDS.

```http
// NasTools 认证
// POST /nastools/approve
{
    "data": "encrypted_auth_data"
}
```

```http
// IYUU 认证
// GET /iyuu/approve?token=xxx&id=1&verity=xxx&provider=iyuu
```

```http
// AMMDS 认证
// POST /ammds/approve
{
    "uid": 1,
    "timestamp": 1705764000,
    "nonce": "random_string",
    "signature": "calculated_signature"
}
```

--------------------------------

### OAuth User Info Endpoint

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Provides user information as an OAuth2 resource server for third-party applications. Requires an Authorization header with an OAuth access token.

```http
// GET /oauth/user-info
// Headers: Authorization: Bearer {oauth_access_token}
```

```json
// Response
{
    "id": 1,
    "username": "example_user",
    "email": "user@example.com",
    "class": 3,
    "uploaded": 107374182400,
    "downloaded": 53687091200
}
```

--------------------------------

### Delete Torrent Bookmark

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Use this endpoint to remove a torrent from the user's bookmark list. Requires the torrent_id in the request body.

```http
// 删除收藏
// POST /api/bookmarks/delete
{
    "torrent_id": 123
}
```

--------------------------------

### Torrent Management API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

APIs for managing torrents, including listing, retrieving details, and uploading.

```APIDOC
## GET /api/torrents/{section?}

### Description
Retrieves a list of torrents, supporting filtering by category, keyword search, and sorting. Requires API Token authentication with `torrent:list` permission.

### Method
GET

### Endpoint
/api/torrents/{section?}

### Parameters
#### Query Parameters
- **filter[title]** (string) - Optional - Filter by title keyword.
- **filter[category]** (integer) - Optional - Filter by category ID.
- **filter[visible]** (integer) - Optional - Filter by visibility (0=all, 1=visible, 2=invisible).
- **filter[bookmark]** (string) - Optional - Filter by bookmark status (include/exclude).
- **sort** (string) - Optional - Sort order (e.g., `-id` for descending ID).
- **include** (string) - Optional - Include associated data (e.g., `user`, `tags`).
- **fields** (string) - Optional - Include additional fields (e.g., `has_bookmarked`, `download_url`).

### Request Example
```bash
curl -X GET "https://your-site.com/api/torrents?filter[title]=keyword&sort=-id&include=user" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **ret** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (object) - Contains torrent data.
  - **data** (array) - List of torrent objects.
    - **id** (integer) - Torrent ID.
    - **name** (string) - Torrent title.
    - **small_descr** (string) - Short description.
    - **size** (integer) - Torrent size in bytes.
    - **seeders** (integer) - Number of seeders.
    - **leechers** (integer) - Number of leechers.
    - **times_completed** (integer) - Number of times completed.
    - **added** (string) - Date and time added.
    - **sp_state** (integer) - Special state.
    - **category** (object) - Category details.
      - **id** (integer) - Category ID.
      - **name** (string) - Category name.
  - **links** (object) - Pagination links.
  - **meta** (object) - Pagination metadata.
    - **current_page** (integer) - Current page number.
    - **total** (integer) - Total number of items.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "id": 123,
                "name": "Example.Movie.2024.1080p.BluRay",
                "small_descr": "优质蓝光资源",
                "size": 8589934592,
                "seeders": 50,
                "leechers": 10,
                "times_completed": 200,
                "added": "2024-01-15 10:30:00",
                "sp_state": 2,
                "category": {
                    "id": 1,
                    "name": "Movies"
                }
            }
        ],
        "links": {},
        "meta": {"current_page": 1, "total": 100}
    }
}
```

## GET /api/detail/{id}

### Description
Retrieves detailed information for a single torrent, including description, file list, and peer information. Requires `torrent:view` permission.

### Method
GET

### Endpoint
/api/detail/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the torrent.

#### Query Parameters
- **include** (string) - Optional - Include associated data (e.g., `user`, `extra`, `tags`).
- **fields** (string) - Optional - Include specific fields (e.g., `description`, `download_url`, `has_bookmarked`).

### Request Example
```bash
curl -X GET "https://your-site.com/api/detail/123?include=user,extra&fields=description,download_url" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **ret** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (object) - Torrent details.
  - **id** (integer) - Torrent ID.
  - **name** (string) - Torrent title.
  - **size** (integer) - Torrent size in bytes.
  - **numfiles** (integer) - Number of files.
  - **seeders** (integer) - Number of seeders.
  - **leechers** (integer) - Number of leechers.
  - **times_completed** (integer) - Number of times completed.
  - **description** (string) - Full torrent description.
  - **download_url** (string) - Direct download URL.
  - **user** (object) - Uploader details.
    - **id** (integer) - Uploader ID.
    - **username** (string) - Uploader username.
  - **tags** (array) - List of tags.
    - **id** (integer) - Tag ID.
    - **name** (string) - Tag name.
    - **color** (string) - Tag color.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 123,
        "name": "Example.Movie.2024.1080p.BluRay",
        "size": 8589934592,
        "numfiles": 5,
        "seeders": 50,
        "leechers": 10,
        "times_completed": 200,
        "description": "详细描述内容...",
        "download_url": "https://your-site.com/download.php?downhash=1.xxxxx",
        "user": {
            "id": 1,
            "username": "uploader"
        },
        "tags": [
            {"id": 1, "name": "BluRay", "color": "#0066cc"}
        ]
    }
}
```

## POST /api/upload

### Description
Uploads a new torrent to the site. Requires `torrent:upload` permission. Supports setting category, subtitle, description, and promotion status.

### Method
POST

### Endpoint
/api/upload

### Parameters
#### Request Body
- **file** (file) - Required - The torrent file.
- **name** (string) - Required - The title of the torrent.
- **descr** (string) - Required - The description of the torrent.
- **type** (integer) - Required - The category ID.
- **small_descr** (string) - Optional - The subtitle or short description.
- **url** (string) - Optional - IMDB link.
- **uplver** (string) - Optional - Set to 'yes' for anonymous upload.

### Request Example
```bash
curl -X POST "https://your-site.com/api/upload" \
  -H "Authorization: Bearer your_api_token" \
  -F "file=@/path/to/movie.torrent" \
  -F "name=Example.Movie.2024.1080p.BluRay" \
  -F "descr=这是一部优秀的电影资源..." \
  -F "type=1" \
  -F "small_descr=优质蓝光" \
  -F "url=https://www.imdb.com/title/tt1234567"
```

### Response
#### Success Response (200)
- **ret** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (object) - Contains the ID of the newly uploaded torrent.
  - **id** (integer) - The ID of the uploaded torrent.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 456
    }
}
```
```

--------------------------------

### User Profile API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Retrieve detailed information about a user, including their upload/download statistics, points, and level.

```APIDOC
## GET /api/profile/{id?}

### Description
Retrieves detailed user information. If no ID is provided, it fetches the currently logged-in user's profile.

### Method
GET

### Endpoint
/api/profile/{id?}

### Parameters
#### Path Parameters
- **id** (integer) - Optional - The ID of the user whose profile to retrieve.

### Request Example
```bash
curl -X GET "https://your-site.com/api/profile/1" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **ret** (integer) - Return code, 0 for success.
- **msg** (string) - Success or error message.
- **data** (object) - Contains user profile details.
  - **id** (integer) - User ID.
  - **username** (string) - User's username.
  - **email** (string) - User's email address.
  - **class** (integer) - User's class level.
  - **class_text** (string) - Textual representation of the user's class.
  - **uploaded** (integer) - Total bytes uploaded.
  - **downloaded** (integer) - Total bytes downloaded.
  - **seedbonus** (float) - User's current seed bonus points.
  - **seed_points** (integer) - User's seed points.
  - **invites** (integer) - Number of available invites.
  - **added** (string) - Timestamp when the user account was created.
  - **last_login** (string) - Timestamp of the user's last login.

#### Response Example
```json
{
    "ret": 0,
    "msg": "success",
    "data": {
        "id": 1,
        "username": "example_user",
        "email": "user@example.com",
        "class": 3,
        "class_text": "Elite User",
        "uploaded": 107374182400,
        "downloaded": 53687091200,
        "seedbonus": 12500.50,
        "seed_points": 85000,
        "invites": 5,
        "added": "2023-01-01 00:00:00",
        "last_login": "2024-01-20 15:30:00"
    }
}
```
```

--------------------------------

### Artisan: Elasticsearch Index Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manages Elasticsearch indexes for full-text search.

```APIDOC
## php artisan es.*

### Description
Commands for managing Elasticsearch indexes.

### Usage
```bash
# Create an Elasticsearch index
php artisan es:create_index

# Delete an Elasticsearch index
php artisan es:delete_index

# Import data into Elasticsearch
php artisan es:import

# View Elasticsearch index information
php artisan es:info
```
```

--------------------------------

### Artisan: MeiliSearch Index Management

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Manages MeiliSearch indexes for search functionality.

```APIDOC
## php artisan meilisearch.*

### Description
Commands for managing MeiliSearch indexes.

### Usage
```bash
# Import data into MeiliSearch
php artisan meilisearch:import

# View MeiliSearch statistics
php artisan meilisearch:stats
```
```

--------------------------------

### OAuth User Info API

Source: https://context7.com/xiaomlove/nexusphp/llms.txt

Provides user information for third-party applications via OAuth2.

```APIDOC
## GET /oauth/user-info

### Description
This endpoint acts as an OAuth2 resource server, allowing third-party applications to retrieve user data.

### Method
GET

### Endpoint
/oauth/user-info

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., Bearer {oauth_access_token}).

### Response
#### Success Response (200)
- **id** (integer) - User ID.
- **username** (string) - User's username.
- **email** (string) - User's email address.
- **class** (integer) - User's class level.
- **uploaded** (integer) - Total bytes uploaded.
- **downloaded** (integer) - Total bytes downloaded.

#### Response Example
```json
{
    "id": 1,
    "username": "example_user",
    "email": "user@example.com",
    "class": 3,
    "uploaded": 107374182400,
    "downloaded": 53687091200
}
```
```