tomio2480 / php-serial
Cross-platform PHP library for serial port communication with microcontrollers
Fund package maintenance!
Requires
- php: ^8.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.91
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
- squizlabs/php_codesniffer: ^3.7
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
PHP でマイコンとシリアル通信するクロスプラットフォームライブラリ。
概要
PySerial や Ruby serialport のような使い勝手を提供。 Windows、Mac、Linux で動作し、Pure PHP 実装。
動作環境
- PHP 8.2 以上
- Windows、Linux、macOS
PHP 本体のセキュリティ修正が提供されているバージョン(サポート対象)で、最新のパッチリリースを使うことを推奨します。
対応する PHP のバージョンは、PHP 本体のサポート期間に合わせます。 セキュリティ修正のみの期間を含め、本体のサポートが終わったバージョンは次のリリースで対応から外します。 PHP 8.1 は 2025-12-31 にサポートが終わったため、v2.0.0 で外しました。
インストール
Composer を使用してインストール:
composer require tomio2480/php-serial
特定のバージョンを指定する場合:
composer require tomio2480/php-serial:^1.3
基本的な使い方
<?php require 'vendor/autoload.php'; use PhpSerial\Configuration; use PhpSerial\SerialPort; $config = new Configuration( baudRate: 9600, dataBits: 8, parity: Configuration::PARITY_NONE, stopBits: Configuration::STOP_BITS_1 ); $port = new SerialPort('/dev/ttyUSB0', $config); $port->open(); // データ送信 $port->write("Hello, Arduino!\n"); // データ受信 $response = $port->readLine(timeout: 2000); echo "Received: {$response}\n"; $port->close();
write(string $data) は、データをすべて送り終えてから戻ります。
戻り値は送ったバイト数で、常に $data の長さと同じです。
期限は「1 文字の最大送信時間(12 ビット分)× バイト数 + 1 秒」で、どの OS でも同じです。
相手が受け取らずに期限を過ぎると、PhpSerial\TimeoutException を送出します。
送れたバイト数は getBytesWritten() で取り出せるため、残りを送り直せます。
use PhpSerial\TimeoutException; try { $port->write($data); } catch (TimeoutException $e) { $rest = substr($data, $e->getBytesWritten()); // 相手の状態を確かめてから $rest を送り直す }
TimeoutException は RuntimeException を継承します。
read(int $length = 1024) は最大 $length バイトを返します。
1 回で確保するバッファの上限は 64 KiB で、上限を超える指定は上限へ丸めます。
1 未満を指定すると RuntimeException を送出します。
設定例
ボーレート
対応するボーレート(bps)は次のとおりです。
110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200, 230400
$config = new Configuration(baudRate: 115200);
パリティ
use PhpSerial\Configuration; // パリティなし $config = new Configuration(parity: Configuration::PARITY_NONE); // 奇数パリティ $config = new Configuration(parity: Configuration::PARITY_ODD); // 偶数パリティ $config = new Configuration(parity: Configuration::PARITY_EVEN);
データビット
対応: 5, 6, 7, 8
$config = new Configuration(dataBits: 8);
ストップビット
use PhpSerial\Configuration; $config = new Configuration(stopBits: Configuration::STOP_BITS_1); // または $config = new Configuration(stopBits: Configuration::STOP_BITS_2);
メソッドチェーン
$config = new Configuration(); $config ->setBaudRate(115200) ->setDataBits(8) ->setParity(Configuration::PARITY_NONE) ->setStopBits(Configuration::STOP_BITS_1);
デバイスパス
Windows
$port = new SerialPort('COM3');
重要: Windows 環境では PHP FFI 拡張の有効化を強く推奨します。
正確で安定したシリアル通信を実現するため、php.ini で FFI を有効にしてください:
extension=ffi ffi.enable=true
FFI 無効時はフォールバック実装が使用されますが、データ受信が動作せず送信のみ可能となります。 詳細は docs/WINDOWS_FFI_SETUP.md を参照してください。
Linux
$port = new SerialPort('/dev/ttyUSB0'); // または $port = new SerialPort('/dev/ttyACM0');
macOS
$port = new SerialPort('/dev/tty.usbserial');
Linux と macOS では、open() が stty でポートを raw モードに設定します。
改行の変換や制御文字の解釈をせず、受け取ったバイトをそのまま扱います。
テスト
環境変数でテスト用デバイスを指定:
# .env.exampleを.envにコピー cp .env.example .env # .envファイルでTEST_SERIAL_PORTを設定 # TEST_SERIAL_PORT=COM3 # テスト実行 composer test
実機なしで送受信を確かめる結合テストもあります。 serdevmock と仮想ポートの対を使います。 CI では、Linux を push と PR のたびに、macOS と Windows を週 1 回と関係する PR で実行します。 手順は docs/INTEGRATION_TESTING.md を参照してください。
使用例
基本的な使用例は examples/basic.php を参照。 複数コマンド送信の例は examples/advanced.php を参照。
開発
品質確認
すべての品質チェックを一度に実行:
composer qa
個別チェック:
composer cs:check # PSR-12準拠チェック composer cs:fixer # コードスタイルチェック composer stan # PHPStan静的解析 (レベル8) composer test # テスト実行
詳細は CONTRIBUTING.md を参照してください。
ライセンス
MIT