# php-brawl-downloader

**Repository Path**: nece001/php-brawl-downloader

## Basic Information

- **Project Name**: php-brawl-downloader
- **Description**: 文件下载器
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-04
- **Last Updated**: 2025-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PHP多线程批量文件下载器

> 一个基于GuzzleHttp的多线程批量文件下载工具，支持大文件分块下载、断点续传、并发控制等功能。

## 功能特性

* 多线程并发下载，提高下载效率
* 大文件自动分块下载，避免内存溢出
* 支持断点续传，意外中断可继续下载
* 可自定义HTTP请求头和Cookie
* 灵活的回调机制，方便监控下载进度
* 支持设置并发数、超时时间等参数

## 安装

```bash
composer require nece001/php-brawl-downloader
```

## 基本用法

### 创建下载器实例

```php
<?php

use Nece\Brawl\Downloader\Downloader;

// 创建下载器实例
$savePath = '/path/to/save/'; // 文件保存路径
$downloader = new Downloader($savePath, [
    'timeout' => 30,
    'http_errors' => false,
    'verify' => false, // 不验证SSL证书
]);
```

### 设置HTTP请求头

```php
// 设置HTTP请求头
$downloader->setHeaders([
    'User-Agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
    'Accept' => '*/*',
]);

// 或者添加单个请求头
$downloader->addHeader('Referer', 'https://example.com');
```

### 设置Cookie

```php
// 设置Cookie数组
$downloader->setCookies([
    'session_id' => 'abc123',
    'user_token' => 'xyz789'
]);

// 添加单个Cookie
$downloader->addCookie('preference', 'dark-mode');

// 从Cookie字符串设置
$downloader->setCookieFromString('name1=value1; name2=value2');
```

### 配置下载参数

```php
// 设置并发数（默认为5）
$downloader->setConcurrency(3);

// 设置大文件阈值（默认为10MB）
$downloader->setLargeFileThreshold(5 * 1024 * 1024); // 5MB

// 设置分块大小（默认为2MB）
$downloader->setChunkSize(1 * 1024 * 1024); // 1MB
```

### 设置回调函数

```php
// 单个文件下载完成回调
$downloader->onComplete(function ($result) {
    echo "文件下载完成: {$result['filename']}\n";
    echo "保存路径: {$result['filepath']}\n";
    echo "文件大小: {$result['size']} 字节\n";
    echo "下载状态: " . ($result['success'] ? '成功' : '失败') . "\n";
    if (!$result['success']) {
        echo "错误信息: {$result['error']}\n";
    }
});

// 所有文件下载完成回调
$downloader->onAllComplete(function ($results) {
    echo "所有文件下载完成，共 " . count($results) . " 个文件\n";
    
    // 统计成功和失败的数量
    $success = 0;
    $failed = 0;
    foreach ($results as $result) {
        if ($result['success']) {
            $success++;
        } else {
            $failed++;
        }
    }
    
    echo "成功: {$success}, 失败: {$failed}\n";
});
```

### 执行下载

```php
// 准备要下载的URL列表
$urls = [
    'https://example.com/file1.zip',
    'https://example.com/file2.pdf',
    'https://example.com/large-file.iso'
];

// 开始下载
$results = $downloader->download($urls);

// 处理下载结果
foreach ($results as $url => $result) {
    echo "URL: {$url}\n";
    echo "文件名: {$result['filename']}\n";
    echo "状态: " . ($result['success'] ? '成功' : '失败') . "\n";
    echo "大小: {$result['size']} 字节\n";
    echo "HTTP状态码: {$result['http_code']}\n";
    echo "下载用时: {$result['time']} 秒\n";
    echo "下载速度: {$result['speed']} 字节/秒\n";
    echo "\n";
}
```

## 使用工厂类创建实例

```php
<?php

use Nece\Brawl\Downloader\Factory;
use Nece\Brawl\Downloader\Config;

// 创建配置对象
$config = new Config();
$config->setValue('save_path', '/path/to/save/');
$config->setValue('user_agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36');
$config->setValue('timeout', 30);
$config->setValue('connect_timeout', 5);
$config->setValue('proxy', 'http://proxy.example.com:8080'); // 可选

// 使用工厂创建下载器实例
$downloader = Factory::create($config);

// 然后可以使用下载器进行下载操作
$urls = ['https://example.com/file1.zip', 'https://example.com/file2.pdf'];
$results = $downloader->download($urls);
```

## 下载结果说明

下载完成后返回的结果数组包含以下信息：

```php
[
    'url' => '文件URL',
    'filename' => '文件名',
    'filepath' => '文件保存路径',
    'size' => '已下载大小（字节）',
    'total_size' => '文件总大小（字节）',
    'speed' => '下载速度（字节/秒）',
    'time' => '下载用时（秒）',
    'http_code' => 'HTTP状态码',
    'error' => '错误信息（如果有）',
    'success' => '是否成功（布尔值）'
]
```

## 注意事项

1. 大文件下载会自动使用分块下载方式，小文件则使用多线程并发下载
2. 默认的大文件阈值为10MB，可以通过`setLargeFileThreshold()`方法调整
3. 默认的分块大小为2MB，可以通过`setChunkSize()`方法调整
4. 默认的并发数为5，可以通过`setConcurrency()`方法调整
5. 下载过程中断点续传信息保存在原文件同目录下的`.resume`文件中