ScrapyardIO FD

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

---

License

MIT — © Angel Gonzalez / Project Saturn Studios