bolk/php-applescript-ffi

Run AppleScript on macOS from PHP via FFI and the Open Scripting Architecture.

dev-main 2026-03-07 12:12 UTC

Requires

• php: ^8.3
• ext-ffi: *

Requires (Dev)

• phpunit/phpunit: ^12.2

MIT

README

Run AppleScript on macOS from PHP through the native Open Scripting Architecture exposed via FFI.

Requirements

• macOS
• PHP 8.3+
• ext-ffi
• FFI must be enabled in php.ini: ffi.enable=true or ffi.enable=preload (when running from CLI). Values true and 1 are both accepted.

Installation

composer require bolk/php-applescript-ffi

Usage

<?php

use Bolk\AppleScript\AppleScript;

$appleScript = new AppleScript();

// Execute and get the result as a string.
echo $appleScript->execute('return (current date) as string'); // current date

// Execute without caring about the result.
$appleScript->run('say "Hello from PHP"');

Runtime Check

Use AppleScript::isSupported() to check the current runtime prerequisites without throwing exceptions. This is handy for graceful degradation, but it does not guarantee that the native macOS bindings will initialize successfully on the first execution call:

if (AppleScript::isSupported()) {
    $appleScript = new AppleScript();
    $appleScript->run('say "Hello from PHP"');
}

You should still be prepared to catch FfiUnavailableException when calling execute() or run().

Security Warning

Never concatenate untrusted user input directly into your AppleScript strings.

AppleScript has access to the underlying system and can execute shell commands (do shell script). Allowing arbitrary user input to be executed as AppleScript is equivalent to a Remote Code Execution (RCE) vulnerability. Always validate and sanitize any variables passed into your scripts.

Exceptions

• UnsupportedPlatformException — not running on macOS.
• FfiUnavailableException — FFI extension is missing, disabled (ffi.enable=false), restricted to preload while not in CLI, or the native macOS FFI bindings fail to initialize.
• ExecutionException — AppleScript execution failed (syntax error, runtime error). The message contains the AppleScript error text when available.

Testing

composer test          # all tests
composer test:unit     # unit tests only
composer test:integration  # integration tests (requires macOS with FFI)