PHP script - detect whether running under linux or Windows?

PHP script - detect whether running under linux or Windows?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Detecting CLI Environment in PHP: A Practical Guide

Determining whether a PHP script is executing on Linux or Windows within a CLI context requires looking beyond standard file paths. While phpinfo() provides an overview, it often lacks the granular detail needed for cross-platform scripting. The most robust approach relies on inspecting the operating system's environment variables and process metadata available to the script at runtime.

The primary method involves checking the PHP_OS constant. This built-in constant explicitly identifies the operating system family. If PHP_OS returns 'Linux', you are on a Unix-like system; if it returns 'Windows_NT', you are on Windows. This is a reliable indicator because PHP initializes this based on the build configuration and runtime environment detection.

$os = PHP_OS;

if ($os === 'Linux') {
    // Execute Linux-specific CLI commands
} elseif ($os === 'Windows_NT') {
    // Execute Windows-specific CLI commands
} else {
    // Fallback or error handling for macOS, BSD, etc.
}

While PHP_OS is effective, relying solely on it can be fragile if the PHP binary was compiled with mismatched expectations or if running inside a container where the build environment differs from the runtime. A more dynamic and often preferred method in CLI scripts is checking the file system path separator. Linux uses forward slashes (/) as directory separators, whereas Windows uses backslashes (\).

$separator = DIRECTORY_SEPARATOR;

if ($separator === '/') {
    // We are on a Unix-like system (Linux, macOS, etc.)
} else {
    // We are on Windows
}

This approach is particularly useful when you need to construct file paths dynamically. However, for executing system commands, you must also consider the shell interpreter and command syntax. On Linux, the default shell is often bash or sh, while Windows defaults to cmd.exe or PowerShell. Attempting to run a Linux-specific command like ls -la directly on Windows without adjustment will fail unless specific tools (like WSL) are present.

if ($separator === '/') {
    // Linux CLI example
    $command = 'ls -la /var/log';
} else {
    // Windows CLI example
    // Note: Use 'cmd.exe' or 'powershell' depending on requirements
    $command = 'dir C:\Windows\System32'; 
}

A critical pitfall in cross-platform CLI scripting is the handling of quotes and escaping. Windows command interpreters are notoriously sensitive to how quotes are nested, often requiring double escapes (\") that Linux shells do not need. Hardcoding escape sequences based on PHP_OS can lead to brittle scripts. Instead, leverage PHP's shell execution functions like shell_exec() or exec() carefully, ensuring arguments are properly sanitized to prevent injection attacks regardless of the OS.

If your project is part of a larger Laravel ecosystem, consider using the Process facade (Laravel\Octane or standard Symfony\Component\Process) rather than calling system commands directly. The Process component abstracts away many of these OS-specific quirks, handling path separators and working directories automatically across platforms.

use Symfony\Component\Process\Process;

$process = new Process($command, $cwd);
$process->run();

// Output the result if any command was executed
echo $process->getOutput();

Using abstraction layers like this reduces technical debt and ensures that your script behaves consistently whether deployed on a standard Linux server or a Windows workstation. Always validate the environment at runtime rather than assuming compatibility, as development environments often differ significantly from production setups.

Our network