https://github.com/peterujah/php-cli-session
A lightweight utility class to manage and inspect CLI session environments in PHP.
https://github.com/peterujah/php-cli-session
Last synced: 10 months ago
JSON representation
A lightweight utility class to manage and inspect CLI session environments in PHP.
- Host: GitHub
- URL: https://github.com/peterujah/php-cli-session
- Owner: peterujah
- License: mit
- Created: 2025-07-26T10:50:56.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-26T11:44:40.000Z (11 months ago)
- Last Synced: 2025-07-26T16:43:56.411Z (11 months ago)
- Language: PHP
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CLI Session Helper for PHP
A lightweight utility class to manage and inspect CLI session environments in PHP.
Designed for cross-platform compatibility (Linux, macOS, Windows) with focus on stream handling, session identification, terminal capability detection, and environmental diagnostics.
> No external dependencies. Built for PHP 7+
---
## Features
- Detects and resolves `STDIN`, `STDOUT`, `STDERR` in CLI environments
- Handles platform-specific stream opening safely
- Retrieves:
- Terminal size (height and width)
- Current user (`whoami`)
- MAC address
- OS and system model
- Shell and terminal name
- Detects:
- ANSI and color support
- Platform type (Windows, macOS, Linux, cloud)
- Generates a **unique system identifier** for CLI sessions
- Silently handles errors using proper fallbacks
---
## Installation
Install via Composer PHP package manager.
```bash
composer require peterujah/php-cli-session
```
---
## Usage
### Initialize CLI streams
```php
use Peterujah\Cli\System\Session;
Session::init(); // Optional if constructor is called
```
### Start PHP session with CLI-safe ID
```php
$sessionId = Session::getSystemId();
session_id($sessionId);
session_start();
```
See working example [CLI Demos](https://github.com/peterujah/php-cli-session/tree/main/tests)
---
## Examples
### Get CLI terminal info
```php
$info = Session::getSystemInfo();
foreach ($info as $item) {
echo $item['Name'] . ': ' . $item['Value'] . PHP_EOL;
}
```
### Detect color and ANSI support
```php
if (Session::isColorSupported()) {
echo "✅ Color output is supported." . PHP_EOL;
}
if (Session::isAnsiSupported()) {
echo "✅ ANSI escape sequences are supported." . PHP_EOL;
}
```
### Detect terminal dimensions
```php
$width = Session::getWidth();
$height = Session::getHeight();
echo "Terminal Size: {$width} x {$height}" . PHP_EOL;
```
---
## Methods Overview
| Method | Description |
| ---------------------------- | -------------------------------------------------------------- |
| `init()` | Initializes CLI stream resources (`STDIN`, `STDOUT`, etc.) |
| `getSystemId()` | Returns a unique, hash-based identifier for the current system |
| `getSystemInfo()` | Returns structured system diagnostics |
| `getTerminalName()` | Returns terminal name (`tty`, PowerShell, etc.) |
| `getMacAddress()` | Retrieves system MAC address |
| `getPid()` | Gets the parent process ID |
| `whoami()` | Gets the current user executing the script |
| `isColorSupported()` | Checks if terminal supports color output |
| `isAnsiSupported()` | Checks if terminal supports ANSI escape codes |
| `getWidth()` / `getHeight()` | Gets terminal width and height |
| `isPlatform($os)` | Checks for OS platform or cloud environment |
---
## Platform Compatibility
| OS | Status |
| -------- | -------------------------------------------- |
| Linux | ✅ Tested |
| macOS | ✅ Tested |
| Windows | ✅ Tested |
| BSD/Unix | ⚠️ Partial support |
| Docker | ✅ Supported (if `tput` or `stty` available) |
---
## License
MIT License — use it, hack it, extend it.
---
## TODO
* Optional support for logging output to a file
* Add unit tests
* CLI command wrapper integration
* PHP framework integration hook