tuuz/net

TuuzNet is a lightweight cURL-based HTTP client library for PHP. Provides clean static interface for GET, POST (JSON/Form/File/Binary), PUT, DELETE requests with customizable headers, timeouts, and SSL configuration.

v1.0.0 2026-07-31 01:53 UTC

Requires

• php: ^8.0
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.0 || ^11.0

MIT

• tobycroft

• network
• php
• curl
• http
• rest
• api
• request
• http-client
• tuuz
• tuuznet

Published on Packagist.org on 2026-07-31 02:27 UTC

README

轻量级 cURL 基础的 PHP HTTP 客户端库，提供简洁的静态接口，支持 GET、POST（JSON/Form/File/Binary）、PUT、DELETE 等常见请求方式。

功能特性

• ✅ GET / POST / PUT / DELETE 常用请求方法
• ✅ JSON 请求 (PostJson)
• ✅ 表单请求 (PostForm)
• ✅ 文件上传 (PostFile)
• ✅ 二进制流传输 (PostBinary)
• ✅ 自定义 Header、超时、Query 参数
• ✅ 完整异常处理与超时检测
• ✅ 默认禁用 SSL 校验（内网/调试友好）
• ✅ 零依赖，仅需 ext-curl + ext-json
• ✅ 内置 Conventional Commits 提交信息分析器，可自动生成包描述、版本号建议、CHANGELOG

安装

通过 Composer 安装：

composer require tuuz/net

要求：

• PHP >= 8.0
• 扩展：curl, json

快速开始

<?php
require __DIR__ . '/vendor/autoload.php';

use TuuzNet\TuuzNet;

// GET 请求
$response = TuuzNet::Get('https://api.example.com/users', [
    'page' => 1,
    'limit' => 20,
]);

// POST JSON
$response = TuuzNet::PostJson('https://api.example.com/users', [], [
    'name' => 'Alice',
    'email' => '[e-mail]',
]);

// POST 表单
$response = TuuzNet::PostForm('https://api.example.com/login', [], [
    'username' => 'admin',
    'password' => '123456',
]);

// 文件上传
$response = TuuzNet::PostFile('https://api.example.com/upload', '/path/to/file.pdf');

// PUT
$response = TuuzNet::Put('https://api.example.com/users/1', [], [
    'name' => 'Bob',
]);

// DELETE
$response = TuuzNet::Delete('https://api.example.com/users/1');

💡 也可以直接用全局类名 TuuzNet::xxx() 调用（无需 use 导入，由 helpers.php 自动注册 class_alias）。

API 参考

所有方法均为静态调用，抛出 \Exception 用于错误和超时处理。

通用参数说明

参数	类型	说明
$base_url / $send_url / $url	string	请求目标 URL
$query	array	URL Query 参数（会以 ?a=1&b=2 拼接到 URL）
$postData	array | string	请求体数据
$headers	array	自定义 HTTP Header（字符串数组，格式 Key: value）
$timeout	int	超时时间（秒），默认 30~60 秒

Get()

TuuzNet::Get(
    string $base_url,
    array  $query = [],
    array  $headers = [],
    int    $timeout = 30
): string

PostJson()

以 Content-Type: application/json 发送 POST 请求，$postData 数组会自动 json_encode（使用 JSON_UNESCAPED_UNICODE）。

TuuzNet::PostJson(
    string $base_url,
    array  $query = [],
    array  $postData = [],
    int    $timeout = 30
): string

PostForm()

以 application/x-www-form-urlencoded 发送表单 POST。

TuuzNet::PostForm(
    string $base_url,
    array  $query = [],
    array  $postData = [],
    int    $timeout = 30
): string

PostFile()

使用 multipart/form-data 上传文件，基于 PHP 原生 CURLFile。

TuuzNet::PostFile(
    string $send_url,
    string $real_path,
    string $fieldName = 'file',
    array  $extraData = [],
    int    $timeout = 60
): string|bool

示例：上传文件并携带额外字段

TuuzNet::PostFile(
    'https://example.com/upload',
    '/data/avatar.png',
    'avatar',
    ['user_id' => 1001, 'type' => 'png']
);

PostBinary()

发送二进制数据（例如图片字节流、protobuf）。返回结构包含响应、错误、HTTP 元信息。

TuuzNet::PostBinary(
    string $url,
    mixed  $data,
    array  $headers = [],
    int    $timeout = 40
): array

返回值：

[
    'result'    => string|false,  // 响应内容
    'error'     => string|null,   // curl 错误信息
    'http_info' => array          // curl_getinfo() 完整信息
]

Put()

发送 PUT 请求，默认 JSON 编码。

TuuzNet::Put(
    string $base_url,
    array  $query = [],
    mixed  $postData = [],
    array  $headers = [],
    int    $timeout = 30
): string

Delete()

发送 DELETE 请求。

TuuzNet::Delete(
    string $base_url,
    array  $query = [],
    array  $headers = [],
    int    $timeout = 30
): string

错误处理

所有请求在失败时均抛出 \Exception：

use TuuzNet\TuuzNet;

try {
    $resp = TuuzNet::PostJson('https://example.com/api', [], ['foo' => 'bar']);
    $data = json_decode($resp, true);
} catch (\Exception $e) {
    // 可能的错误：超时、DNS 解析失败、连接拒绝、SSL 错误等
    echo '请求失败: ' . $e->getMessage();
}

CommitAnalyzer - 提交信息分析器

本包内置基于 Conventional Commits 规范的提交分析器，可自动分析 Git 日志、生成版本号建议、CHANGELOG、以及包提交用的 Description。

直接使用（CLI）

# 分析最近 10 条提交，目标版本设为 1.0.0
composer analyze -- 1.0.0 10

# 分析 v1.0.0 到 HEAD 之间的所有提交
composer analyze -- 1.1.0 v1.0.0..HEAD

输出包含：有效性统计、按类型/Scope分布图、无效提交提示、自动生成的包描述（Summary/Keywords/Highlights）、完整 CHANGELOG。

代码调用

use TuuzNet\CommitAnalyzer;

$analyzer = new CommitAnalyzer();

// 1. 解析单条提交
$parsed = $analyzer->parseCommit('feat(net)!: add PUT and DELETE methods');
// => ['type' => 'feat', 'scope' => 'net', 'breaking' => true, 'subject' => '...', ...]

// 2. 验证提交合规性
$result = $analyzer->validateCommit('bad commit message');
// => ['valid' => false, 'errors' => [...], 'warnings' => [...]]

// 3. 批量分析
$batch = $analyzer->analyzeBatch($commitMessages);
// => ['total', 'valid', 'by_type', 'breaking', 'version_bump', 'stats', ...]

// 4. SemVer 版本建议
$ver = $analyzer->suggestNextVersion('1.2.3', $commitMessages);
// => ['current' => '1.2.3', 'next' => '2.0.0', 'bump' => 'major', 'reason' => '...']

// 5. 生成 CHANGELOG
$changelog = $analyzer->generateChangelog('1.3.0', $commitMessages);

// 6. 生成 Composer 包提交描述（Packagist/Release Notes 用）
$desc = $analyzer->generatePackageDescription('tuuz/net', '1.3.0', $commitMessages);
echo $desc['description'];     // 完整包描述段落
echo $desc['release_notes'];   // 完整 CHANGELOG
print_r($desc['keywords']);    // 包关键词
print_r($desc['highlights']);  // 亮点摘要（Features/Breaking Changes 等）

// 7. 读取 Git 日志 + 一键分析
$commits = CommitAnalyzer::fetchGitCommits('HEAD~20..HEAD');
CommitAnalyzer::analyze();   // CLI 美化输出

支持的 Conventional Commits Type

type	说明
feat	新增功能
fix	修复 bug
docs	文档变更
style	代码风格（非功能）
refactor	重构
perf	性能优化
test	测试相关
build	构建系统
ci	CI/CD 配置
chore	杂项维护
revert	回滚

示例提交：

feat(http): add custom header support for Get()
fix(curl): fix timeout exception message
docs!: rewrite README and migrate to new API (BREAKING CHANGE)

目录结构

php_tuuz_net/
├── src/
│   ├── Net.php              # 核心 cURL HTTP 客户端
│   ├── TuuzNet.php          # 静态 Facade（TuuzNet::xxx）
│   ├── CommitAnalyzer.php   # Conventional Commits 分析 + 包描述生成
│   └── helpers.php          # 注册全局类名别名 TuuzNet
├── composer.json
├── vendor/ (composer 生成)
├── phpunit.xml (如有)
└── README.md

License

MIT License © tobycroft