File

Local and remote file reads behind host and path allowlists

Table of contents

Namespace: Com\Tecnick\File

File: File.php line 36

Local and remote file reads behind host and path allowlists

Tags

Methods

__construct()

File: File.php line 158

public __construct([array<string|int, string> $allowedHosts = [] ][, int $maxRemoteSize = 52428800 ][, array<int, bool|int|string|callable|resource> $curlopts = [] ][, array<int, bool|int|string|callable|resource>|null $defaultCurlOpts = null ][, array<int, bool|int|string|callable|resource>|null $fixedCurlOpts = null ][, array<string|int, string> $allowedPaths = [] ][, bool|null $caseSensitivePaths = null ]) : mixed

Parameters

  • $allowedHosts : array<string|int, string> = []: Allowlist of trusted hostnames.
  • $maxRemoteSize : int = 52428800: Maximum size in bytes for remote file reads. Must be positive.
  • $curlopts : array<int, bool|int|string|callable|resource> = []: Custom cURL options to merge over defaults.
  • $defaultCurlOpts : array<int, bool|int|string|callable|resource>|null = null: Override for the default cURL options; null uses CURLOPT_DEFAULT.
  • $fixedCurlOpts : array<int, bool|int|string|callable|resource>|null = null: Override for the fixed cURL options; null uses CURLOPT_FIXED.
  • $allowedPaths : array<string|int, string> = []: Allowlist of trusted file paths.
  • $caseSensitivePaths : bool|null = null: Override for path case-sensitivity: null = auto-detect, true = case-sensitive, false = case-insensitive.

Tags

  • throws: Exception when $maxRemoteSize is not positive.

fileGetContents()

File: File.php line 366

public fileGetContents(string $file) : string

The file can be also an URL.

Parameters

  • $file : string: Name of the file or URL to read.

Tags

Return values

string

fopenLocal()

File: File.php line 278

public fopenLocal(string $file, string $mode) : resource

Parameters

  • $file : string: Name of the file to open.
  • $mode : string: Type of access required to the stream. The binary flag (‘b’) is added when absent.

Tags

Return values

resource —

Returns a file pointer resource on success.

fReadInt()

File: File.php line 306

public fReadInt(resource $resource) : int

Parameters

  • $resource : resource: A file system pointer resource that is typically created using \fopen().

Tags

Return values

int —

4-byte integer.

getAltFilePaths()

File: File.php line 832

public getAltFilePaths(string $file) : array<int, string>

Parameters

  • $file : string: Name of the file or URL to read.

Return values

array<int, string> —

List of possible alternative file paths or URLs.

getFileData()

File: File.php line 389

public getFileData(string $file) : string|false

The file can be also an URL.

Parameters

  • $file : string: Name of the file or URL to read.

Tags

  • throws: Exception in case the remote transfer is aborted due to max size.

Return values

string|false —

File content or FALSE in case the file is unreadable

getLocalFileData()

File: File.php line 408

public getLocalFileData(string $file) : string|false

Parameters

  • $file : string: Name of the file to read.

Return values

string|false —

File content, or FALSE when the path is not allowlisted, not a valid local path, or unreadable.

getMaxRemoteSize()

File: File.php line 262

public getMaxRemoteSize() : int

Return values

int

getUrlData()

File: File.php line 678

public getUrlData(string $url) : string|false

The cURL path is always used, independently of the allow_url_fopen ini setting.

The response is buffered in memory, so a transfer costs up to $maxRemoteSize bytes of PHP memory. The limit is enforced by a write callback that counts the bytes as they are buffered.

Parameters

  • $url : string: URL to read.

Tags

  • throws: Exception if the remote transfer is aborted due to max size, or a configured cURL option is not valid or cannot be applied.

Return values

string|false —

Remote content, or FALSE when the URL is not allowlisted, the response is an unfollowed redirect, or the transfer fails.

isAllowedFile()

File: File.php line 1128

public isAllowedFile(string $file) : bool

By-value counterpart of isValidFile(), callable with a literal or any other expression and leaving the argument untouched.

Parameters

  • $file : string: File path to validate.

Return values

bool

isAllowedUrl()

File: File.php line 1115

public isAllowedUrl(string $url) : bool

By-value counterpart of isValidURL(), callable with a literal or any other expression and leaving the argument untouched.

Parameters

  • $url : string: URL to validate.

Return values

bool

isValidFile()

File: File.php line 1415

public isValidFile(string &$file) : bool

Returns true when:

  • wildcard trust (’*’) is enabled, or
  • the normalized local path starts with one trusted allowlist prefix.

Returns false for parent-directory traversal patterns (’..’), non-file schemes, and when no allowlist entry matches. When the allowlist is empty (default), every path is rejected.

The ‘file://’ schema is added to the input $file parameter if missing.

Parameters

  • $file : string: File path to validate.

Return values

bool

isValidURL()

File: File.php line 1048

public isValidURL(string &$url) : bool

Returns true only when the URL parses correctly, uses the http or https scheme, and has a non-empty host trusted by isValidUrlHost().

$url is passed by reference and is replaced with its trimmed form, so it must be a variable. Use isAllowedUrl() to validate a literal or any other expression.

Parameters

  • $url : string: URL to validate.

Return values

bool

resolveLocalPath()

File: File.php line 856

public resolveLocalPath(string $file[, array<string|int, string> $baseDirs = [] ]) : string

Turns an existing local relative path into an absolute canonical path when one of the provided base directories matches. No trust boundary is checked and no file is read, so the result must be passed through isValidFile() or isAllowedFile() before it is handed to any reader.

Parameters

  • $file : string: Local file path to resolve.
  • $baseDirs : array<string|int, string> = []: Candidate base directories checked in order.

Return values

string

rfRead()

File: File.php line 329

public rfRead(resource|null $resource, int $length) : string

Reads up to length bytes from the file pointer referenced by handle. Reading stops as soon as one of the following conditions is met: length bytes have been read; EOF (end of file) is reached.

Parameters

  • $resource : resource|null: A file system pointer resource that is typically created using \fopen().
  • $length : int: Number of bytes to read; must be positive.

Tags

  • throws: Exception when $length is not positive, or in case of a read error.

Return values

string

setAllowedHosts()

File: File.php line 213

public setAllowedHosts(array<string|int, string> $allowedHosts) : static

Parameters

  • $allowedHosts : array<string|int, string>: Trusted hostname strings.

Return values

static

setAllowedPaths()

File: File.php line 224

public setAllowedPaths(array<string|int, string> $allowedPaths) : static

Parameters

  • $allowedPaths : array<string|int, string>: Trusted file path strings.

Return values

static

setCaseSensitivePaths()

File: File.php line 236

public setCaseSensitivePaths(bool|null $caseSensitivePaths) : static

Parameters

  • $caseSensitivePaths : bool|null: null = auto-detect per platform/volume, true = case-sensitive, false = case-insensitive.

Return values

static

setCurlOpts()

File: File.php line 202

public setCurlOpts(array<int, bool|int|string|callable|resource> $curlopts) : static

Parameters

  • $curlopts : array<int, bool|int|string|callable|resource>: Custom cURL options to merge over defaults.

Return values

static

setMaxRemoteSize()

File: File.php line 249

public setMaxRemoteSize(int $maxRemoteSize) : static

Parameters

  • $maxRemoteSize : int: Maximum allowed bytes; must be positive.

Tags

  • throws: Exception when $maxRemoteSize is not positive.

Return values

static