swoole/swoole-src v6.1.0-rc1

on GitHub

Standard Library Extension

In version 6.1, Swoole-Cli will introduce extended syntax for the PHP standard library, providing additional new syntax while maintaining full compatibility with the official PHP syntax. These new extended syntax features are entirely optional and do not affect existing PHP code. The standard library extension syntax will be implemented in the stdext module of ext-swoole.

• swoole-cli users can use it directly without any additional parameters.
• ext-swoole users need to add --enable-swoole-stdext during compilation to enable it.
• stdext can be used in php-cli, php-fpm, cli-http-server, and swoole modes.

1. Object-Oriented Basic Types

Version 6.1 implements object-oriented encapsulation of basic types such as array, string, and stream, supporting method calls in an object-oriented style. Built-in methods can be directly called on variables of these types.

The built-in methods for basic types still utilize the PHP standard library. These methods correspond one-to-one with PHP's str_ or array_ series functions. For example, $text->replace() corresponds to the str_replace function. The underlying implementation only adjusts function names, slightly modifies the parameter order for a few methods, and adjusts parameter and return value types for several others. For details, please refer to the Swoole Documentation.

$text = 'Hello Swoole';
var_dump($text->length());
echo $text->lower()->replace("swoole", "php");

2. Typed-Array

Typed arrays can enforce type constraints, such as Map or ArrayList, and restrict the types of keys and values. Multi-level nested formats are supported. Typed arrays are still essentially array types, with parameter checks performed only during write operations. Typed arrays can be passed as array to other functions or class methods.

$array = typed_array('<int, string>');
$array[1000] = "hello"; // Correct
$array[2000] = 2025; // Error, throws an exception

✨ New Features

• Default llHTTP Parser: Starting from v6.1.0, Swoole uses the higher-performance llhttp as the default HTTP message parser, replacing http_parser.
• Coroutine-Based File Download: Swoole\Coroutine\Http\Client now supports full coroutine-based file download operations.
• Asynchronous File Truncation: Added support for iouring ftruncate, expanding asynchronous file operation capabilities.

🐛 Bug Fixes

• Thread Mode Optimization:
  • Fixed the issue where hook_flags settings were ineffective in SWOOLE_THREAD mode.
  • Fixed the issue where heartbeat threads held invalid pointers and accessed freed memory after worker threads restarted due to reaching the max_request limit.
  • Fixed the issue where Task processes could not be restarted individually.
• Stability Improvements:
  • Fixed the issue where synchronous processes (including manager and task processes) could not use process::signal() properly.
  • Corrected the resource cleanup mechanism when worker processes exit abnormally.
  • Resolved compilation failures on the Cygwin platform.
  • Fixed the issue where curl could not reuse sockets when keepalive was enabled.
  • Improved the logging component to address data consistency issues in multi-threaded mode.
  • Fixed compilation failures of the futex feature in io_uring on ubuntu24.04.
  • Fixed compilation failures caused by struct sequential assignment on older Linux systems.
  • Fixed the issue where the id property of directly instantiated Swoole\Process objects was uninitialized.
  • Fixed the missing --enable-zstd option in composer.json when compiling Swoole with PIE.
• Compatibility Improvements:
  • Fixed compatibility issues with php_swoole_register_shutdown_function on PHP 8.5.
  • Corrected the handling of null parameters in Swoole\Table::get().
• Protocol Handling:
  • Optimized the handling of duplicate fields in HTTP request and response headers to ensure proper merging.
  • Fixed the issue where a warning about an unknown compression method was triggered when processing client Accept-Encoding: zlib headers without zlib installed.

Deprecations

• Support for the select event mechanism has been removed. select only supports event monitoring for up to 1024 handles and has significant limitations. On platforms that do not support epoll/kqueue, poll will be used as the event polling mechanism, enabling support for high concurrency even on the Cygwin platform.
• The second parameter $waitEvent in Swoole\Server::stop() has been deprecated. Please use the reload_async parameter instead.

🛠️ Architectural Optimizations

Version 6.1 adds extensive unit tests for core modules, increasing test coverage to 86%. By systematically supplementing test cases and refactoring underlying code logic, combined with full static code analysis using the clang-tidy toolchain, automated code formatting and redundancy cleanup have been achieved, significantly improving code readability and maintainability.

• Optimized the underlying SSL module.
• Optimized the underlying Socket module.
• Refactored the underlying synchronous signal module.
• Refactored the underlying reactor and string modules.
• Refactored the underlying dynamic log file reloading mechanism based on SIGRTMIN signals.
• Optimized the underlying static file server by removing C-style code and unifying it into C++-style code.
• Optimized thread initialization logic to improve multi-threaded performance. Memory for independent management structures is now managed separately, eliminating the need for locks during thread creation and exit.
• Removed the socket_dontwait option from the underlying async module, as it is deprecated.
• Improved test coverage for WebSocket mask handling.
• Optimized the sendfile functionality to avoid setting the tcp_cork option for files smaller than 64KB.
• Added unit tests for aarch64 and macOS environments.
• Optimized underlying client network address resolution and settings.
• Added ssl_cafile/ssl_capath configuration items for the Server module.
• Added the print_backtrace_on_error configuration, which prints C function stack traces when location errors occur.
• Added the Address Sanitizer debugging tool.
• Added Cygwin testing, significantly improving compatibility and stability on the Cygwin platform.
• On macOS systems, the kqueue event mechanism does not support cross-process pipe event monitoring, making it impossible to use SWOOLE_PROCESS mode and Task processes. Therefore, the system defaults to using poll as the underlying event mechanism. To enable kqueue, manually activate it using Swoole\Server::set(['enable_kqueue' => true]) and swoole_async_set(['enable_kqueue' => true]).

⚠️ Note

• This version is an RC (Release Candidate) and not an official release. It is recommended for use only in testing environments and should not be used in production.

🙏 Thank You

Sincere thanks to @matyhtf @jingjingxyk @sy-records @KIMDONGYEON00 @ServBayDev @NathanFreeman and all contributors for their professional efforts. Swoole is stronger because of you! Wishing all open-source community partners good health, success in all endeavors, and smooth work.

标准库扩展

6.1 版本 Swoole-Cli 将增加 PHP 标准库扩展语法，在保持对 PHP 官方语法完整兼容的同时，提供一些额外的新语法。这些新的扩展语法均是可选的，不影响现有的PHP代码。标准库扩展语法将在ext-swoole的stdext模块中实现。

• swoole-cli 用户，可直接使用，无需设置任何额外的参数
• ext-swoole 的用户，需在编译时添加--enable-swoole-stdext来启用
• stdext 在 php-cli、php-fpm、cli-http-server、swoole 模式均可使用

1. 基础类型对象化

6.1 版本实现了array/string/stream基础类型的对象化封装，支持面向对象风格的方法调用，可直接对这些类型的变量调用内置方法。

基础类型的内置方法实际上仍然是调用PHP标准库实现的，内置方法与PHP的str_或array_系列函数是一一对应关系，例如$text->replace()对应的函数是str_replace。底层仅调整了函数名称，少量方法调整了参数顺序，还有几个方法调整了参数和返回值类型，详情请查看 Swoole 文档。

$text = 'Hello Swoole';
var_dump($text->length());
echo $text->lower()->replace("swoole", "php");

2. Typed-Array 强类型数组

可限制数组类型，如：Map或ArrayList，以及限制key与value的类型。支持多层嵌套格式。typed array实际上依然是array类型，底层仅在写入时进行参数检查。typed array可作为array传递给其他函数或类方法。

$array = typed_array('<int, string>');
$array[1000] = "hello"; // 正确
$array[2000] = 2025; // 错误，抛出异常

✨ 新特性

• llHTTP 默认解析器：自 v6.1.0 起，Swoole 采用性能更优的 llhttp 替代 http_parser 作为默认 HTTP 报文解析器。
• 协程化文件下载：Swoole\Coroutine\Http\Client 现支持完整的协程化文件下载操作。
• 异步文件截断：新增 iouring ftruncate 支持，扩展异步文件操作能力。

🐛 Bug 修复

• 线程模式优化：
  • 修复 SWOOLE_THREAD 模式下 hook_flags 设置失效问题。
  • 修复因工作线程达到max_request限制重启后，导致心跳线程持有失效指针并访问已释放内存的问题。
  • 修复不支持单独重启Task进程的问题。
• 稳定性提升：
  • 修复同步进程（含 manager 进程和 task 进程）无法正常使用process::signal()的问题。
  • 修正工作进程异常退出时的资源清理机制。
  • 解决 Cygwin 平台编译失败问题。
  • 修复curl开启keepalive无法复用socket的问题。
  • 改进日志组件以解决多线程模式下的数据一致性问题。
  • 修复io_uring的futex特性在ubuntu24.04编译失败的问题。
  • 修复结构体顺序赋值在低版本的linux系统会编译失败的问题。
  • 修复直接实例化的Swoole\Process对象其id属性未初始化的问题。
• 修复使用PIE编译swoole时，composer.json文件缺少--enable-zstd的选项的问题。
• 兼容性改进：
  • 修复 PHP 8.5 下 php_swoole_register_shutdown_function 兼容性问题。
  • 修正 Swoole\Table::get() 对 null 参数的处理。
• 协议处理：
  • 优化HTTP请求头与响应头中重复字段的处理机制，确保其正确合并。
  • 修复当系统没有zlib时，处理客户端Accept-Encoding: zlib请求头会触发未知压缩方法警告的问题。

废弃

• 不再支持select事件机制，select仅支持1024个句柄的事件监听，存在严重缺陷，在不支持epoll/kqueue的平台将使用poll作为事件轮训机制，这使得Cygwin平台下也可以支持大量并发。
• 在Swoole\Server::stop()方法中，第二个参数$waitEvent已被废弃，请使用reload_async参数。

🛠️ 架构优化

6.1版本增加了大量核心模块的单元测试，测试覆盖率提升至86%。通过系统性地补充测试用例并重构底层代码逻辑，同时结合clang-tidy工具链开展全量静态代码分析，实现了代码的自动化格式规整与冗余清理，使得代码可读性与可维护性得到显著提升。

• 优化底层SSL模块。
• 优化底层Socket模块。
• 重构底层同步信号模块。
• 重构底层reactor和string模块。
• 重构底层基于SIGRTMIN信号实现日志文件动态重载。
• 优化底层静态文件服务器，移除C风格代码，统一为C++风格的代码。
• 优化线程初始化逻辑，提高多线程性能，独立管理结构内存，线程创建和退出不需要再加锁。
• 移除底层async模块中的socket_dontwait选项，该选项已废弃。
• 完善WebSocket掩码处理的测试覆盖。
• 优化sendfile功能，当文件小于64KB时不设置tcp_cork选项。
• 增加aarch64和macOS环境下的单元测试。
• 优化底层客户端网络地址解析和设置。
• 为 Server模块增加ssl_cafile/ssl_capath配置项。
• 增加print_backtrace_on_error配置，此配置可以在发生位置错误时候，打印C函数的堆栈。
• 增加Address Sanitizer调试工具。
• 增加Cygwin测试，显著提升Cygwin平台下的兼容性和稳定性
• 在 macOS 系统中，由于 kqueue 事件机制不支持跨进程管道事件监听，导致无法使用 SWOOLE_PROCESS 模式和 Task 进程功能。因此，系统将默认采用 poll 作为底层事件机制。如需启用 kqueue，可以通过Swoole\Server::set(['enable_kqueue' => true])和swoole_async_set(['enable_kqueue' => true])方法手动开启。

⚠️ 注意

• 该版本为RC版本非正式版，仅推荐在测试环境中使用，不建议在生产环境中使用。

🙏 致谢

诚挚感谢 @matyhtf @jingjingxyk @sy-records @KIMDONGYEON00 @ServBayDev @NathanFreeman 所有贡献者的专业付出，Swoole 因你们而更强大！愿开源社区伙伴身体健康，万事如意，工作顺利。

翻译成英文