README

dept-of-scrapyard-robotics/fd — file descriptor module for the ScrapyardIO Framework.

Provides a lightweight PHP layer over the ext-fd extension. It exposes simple helper functions for opening, closing, reading, and writing raw file descriptors, plus reusable traits, attributes, and enums for higher-level ScrapyardIO packages.

Requirements

PHP ^8.3
ext-fd 0.1.0 (Zephir extension — see DeptOfScrapyardRobotics/FD for build & install instructions)
dept-of-scrapyard-robotics/support ^0.3.0
A UNIX-like environment supported by ext-fd

Installation

composer require dept-of-scrapyard-robotics/fd

Quick Start

Opening and closing a device

use ScrapyardIO\FD\Enums\FileControlFlag;

$fd = fd_open('/dev/i2c-1', FileControlFlag::O_RDWR->value);

if ($fd < 0) {
    throw new RuntimeException('Unable to open device');
}

$bytes = fd_read($fd, 2);

fd_close($fd);

Writing to a descriptor

use ScrapyardIO\FD\Enums\FileControlFlag;

$fd = fd_open('/dev/ttyUSB0', FileControlFlag::O_WRONLY->value);

fd_write($fd, "\x3A", 1);
fd_close($fd);

API Reference

Helper Functions

Autoloaded global helper functions that forward directly to the ext-fd extension.

Function	Returns	Description
`fd_open(string $device_path, int $flags)`	`int`	Open a file or device and return its file descriptor
`fd_close(int $fd)`	`int`	Close an open file descriptor
`fd_read(int $fd, int $bytes_to_read)`	`string`	Read up to the requested number of bytes
`fd_write(int $fd, string $data, int $bytes_to_write)`	`int`	Write bytes to the descriptor
`fd_add_flags(int $fd, int $flags)`	`int`	Add file status flags with `fcntl()`

`FileControlFlag`

Enum of common fcntl.h/POSIX open flags.

Case	Value	Description
`O_RDONLY`	`0`	Open read-only
`O_WRONLY`	`1`	Open write-only
`O_RDWR`	`2`	Open read/write
`O_APPEND`	`1024`	Append on each write
`O_ASYNC`	`8192`	Enable signal-driven I/O
`O_CLOEXEC`	`524288`	Close on `exec()`
`O_CREAT`	`64`	Create file if it does not exist
`O_DIRECT`	`16384`	Minimize cache effects
`O_DIRECTORY`	`65536`	Fail if path is not a directory
`O_DSYNC`	`4096`	Synchronized writes
`O_EXCL`	`128`	Exclusive create
`O_NOATIME`	`262144`	Do not update access time
`O_NOCTTY`	`256`	Do not assign controlling terminal
`O_NOFOLLOW`	`131072`	Fail on symlink
`O_NONBLOCK`	`2048`	Non-blocking I/O
`O_PATH`	`2097152`	Obtain path-only descriptor
`O_SYNC`	`1052672`	Fully synchronized I/O
`O_TMPFILE`	`4259840`	Create unnamed temporary file
`O_TRUNC`	`512`	Truncate existing file

`FileDescriptors`

Reusable trait for ScrapyardIO classes that open their descriptor from annotated properties.

use ScrapyardIO\FD\Attributes\FDFlags;
use ScrapyardIO\FD\Attributes\FilePath;
use ScrapyardIO\FD\Concerns\FileDescriptors;
use ScrapyardIO\FD\Enums\FileControlFlag;

class Device
{
    use FileDescriptors;

    #[FilePath]
    public readonly string $devicePath;

    #[FDFlags]
    public readonly int $flags;

    public function __construct()
    {
        $this->devicePath = '/dev/i2c-1';
        $this->flags = FileControlFlag::O_RDWR->value;

        $fd = $this->fOpen();
    }
}

Method	Returns	Description
`fOpen()`	`int`	Reflects the annotated path and flags properties, then opens the descriptor

Attributes

Marker attributes used by FileDescriptors.

Attribute	Applied To	Description
`#[FilePath]`	Property	Marks the property containing the device path
`#[FDFlags]`	Property	Marks the property containing the open flags
`#[FileDescriptor]`	Property	Marks the property that stores the resulting descriptor

scrapyard-io / fd

Maintainers

Package info

Statistics

Security