README

Install the dependencies with Composer:

Run composer install to install the project dependencies.

Bot example

A production-ready example, bot.php, is included. It sends periodic OSC messages (sender-only).

Listener and acknowledgement functionality has been moved to the separate entrypoint script osc_listener.php.

Environment variables for bot.php:

• OSC_DEST – remote IP to send messages to (default 127.0.0.1)
• OSC_PORT – remote port to send messages to (default 9000)
• OSC_INTERVAL – send interval in seconds (default 5)
• OSC_ADDRESS – OSC address for heartbeat messages (default /bot/heartbeat)

Examples:

Run the bot with defaults:

php bot.php

Send to a custom destination:

OSC_DEST=192.168.1.50 OSC_PORT=3890 OSC_INTERVAL=2 OSC_ADDRESS=/my/bot php bot.php

Start the separate listener (acknowledgement service) in another terminal:

php osc_listener.php

Examples

See examples.md for more usage examples, including the ReactPHP UDP server (server.php) and how to run it together with bot.php for end-to-end testing.

php-osc

PSR-4 version of Open Sound Control (OSC) Client Library for PHP

Authors:

• Andy W. Schmeder andy@a2hd.com (original, 2003-2007)
• Jason Soares jsoares@theexperiment.org (PSR-4 update)
• Valithor Obsidion valithor@discordphp.org (maintainer, 2026-present)

Copyright:

• Copyright (c) 2003-2007 Andy W. Schmeder
• Copyright (c) 2026-present Valithor Obsidion

Version: 2.0

Requirements: PHP >= 8.1.2

For information about Open Sound Control, see http://www.opensoundcontrol.org/

Known Issues

• Listener callbacks in automated tests: The earlier external-process integration test (starting server.php and osc_listener.php as detached processes) failed to observe the server->listener callback in the automated PHPUnit run on Windows. This was caused by process-start timing and platform-specific spawn/quoting behavior. As a result we now provide an in-process integration test that is reliable under PHPUnit: tests/IntegrationTest.php.

• Manual run that did work: A manual interactive run did exercise the end-to-end flow successfully — start the server and listener, send a probe, and observe the callback/ack cycle in the logs. Example commands used interactively in PowerShell:

  • Start the server (foreground):

    php server.php

  • Start the listener (foreground):

    php osc_listener.php

  • Send a probe to trigger the server callback (helper script):

    php tests/probe_9001.php

  The listener log (osc-listener.log) then shows the received probe and the ack sent back.

• Why this matters: If you rely on automated external-process integration tests on Windows CI, prefer the in-process ReactPHP test harness provided in tests/IntegrationTest.php or run the manual commands interactively. If you want the external-process test to work in CI, it may require platform-specific adjustments to process startup and timeouts.