README

PHP utilities for low-level file access and byte-level reading.

💖 Part of the tc-lib-pdf / TCPDF ecosystem (100M+ installs). Sponsor its maintenance →

Overview

tc-lib-file provides safe primitives for opening files, reading bytes, and handling binary-oriented workflows used by higher-level PDF and document libraries.

The package is intentionally small but critical: it centralizes low-level I/O concerns so higher-level libraries can focus on document semantics instead of stream safety and byte handling. This separation improves reliability, testability, and reuse across the broader Tecnick ecosystem.

Features

File Access

• Local and URL-backed file reading helpers
• Path-safety checks for local operations
• cURL-based retrieval options for remote resources

Binary Utilities

• Byte, integer, and structured binary reads
• Helpers used by parser and image/font import stacks
• Error handling via typed exceptions

Requirements

• PHP 8.2 or later
• Extensions: curl, pcre
• Composer

Installation

composer require tecnickcom/tc-lib-file

Quick Start

<?php

require_once __DIR__ . '/vendor/autoload.php';

$file = new \Com\Tecnick\File\File(
	allowedHosts: ['example.com', 'cdn.example.com'],
	allowedPaths: [__DIR__, '/var/app/uploads'],
	curlopts: [
		CURLOPT_MAXREDIRS => 3,
	],
);
$fh = $file->fopenLocal(__FILE__, 'rb');
$header = $file->fReadInt($fh);

var_dump($header);

Security Configuration (Required)

File defaults to strict-deny behavior for host and path validation.

• allowedHosts defaults to an empty array, so remote URLs and host-based alternate path resolution are rejected unless you explicitly trust hosts.
• allowedPaths defaults to an empty array, so local file operations are rejected unless you explicitly trust path prefixes.

You should always pass explicit allowlists in the constructor (or set them immediately via setters) for production use.

Example:

$file = new \Com\Tecnick\File\File(
	allowedHosts: ['example.com'],
	allowedPaths: ['/srv/my-app/data'],
);

// Equivalent runtime configuration:
$file
	->setAllowedHosts(['example.com'])
	->setAllowedPaths(['/srv/my-app/data']);

Avoid wildcard trust ('*') unless you fully control all inputs and deployment boundaries.

Redirect Handling via CURLOPT_MAXREDIRS

Redirect validation is enabled when CURLOPT_MAXREDIRS is non-zero.

• CURLOPT_MAXREDIRS => 0 (default): no redirect-follow validation callback is installed.
• CURLOPT_MAXREDIRS > 0: redirects are processed and each Location target is validated.

To allow redirects, set a positive max-redirs value and ensure redirect target hosts are present in allowedHosts.

$file = new \Com\Tecnick\File\File(
	allowedHosts: ['example.com', 'downloads.example.com'],
	curlopts: [
		CURLOPT_MAXREDIRS => 5,
	],
);

Platform notes

The library runs on Linux, macOS, and Windows. Path validation adapts to the host filesystem; a few platform behaviors are worth knowing.

Path case-sensitivity

Allowlist matching follows the filesystem's case rules:

• Linux — case-sensitive.
• Windows — case-insensitive.
• macOS — per-volume: the default APFS/HFS+ volume is case-insensitive, but case-sensitive volumes exist. The library probes the actual volume and falls back to case-insensitive when it cannot.

If auto-detection is wrong for your deployment (for example, data on a case-sensitive macOS volume, or a case-insensitive mount on Linux), set it explicitly:

$file = new \Com\Tecnick\File\File(
	allowedPaths: ['/srv/my-app/data'],
	caseSensitivePaths: true, // or false; null (default) = auto-detect
);

// or at runtime:
$file->setCaseSensitivePaths(true);

The same override makes the behavior testable on any host (the CI runs on Linux only — Windows and macOS are validated locally).

Unicode (macOS)

Default macOS volumes are normalization-insensitive (é composed vs. decomposed name the same file). When ext-intl is installed, the library normalizes paths to NFC before comparison so the allowlist matches consistently; without ext-intl it degrades to a byte comparison.

Binary reads

fopenLocal() forces the binary (b) stream flag when absent, so byte-level reads are not altered by Windows text-mode CRLF translation. POSIX systems are unaffected.

Windows known limitations

These inputs are intentionally not treated as trusted/canonical and are not specially expanded before allowlist matching: 8.3 short names (PROGRA~1), Alternate Data Streams (file.txt:stream, ::$DATA), trailing dots/spaces, and reserved device names (CON, NUL, ...). UNC paths (\\server\share) are matched only when explicitly allowlisted — note the network-access implication.

Development

make deps
make help
make qa

Packaging

make rpm
make deb

For system packages, bootstrap with:

require_once '/usr/share/php/Com/Tecnick/File/autoload.php';

Contributing

Contributions are welcome. Please review CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.