Table of contents
Namespace: Com\Tecnick\File
class File
Source: src/File.php:36
Local and remote file reads behind host and path allowlists
Methods
__construct()
Initialize the File object.
public __construct(
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,
string[] $allowedPaths = [],
bool|null $caseSensitivePaths = null
)
Parameters:
$allowedHosts(string[]): Allowlist of trusted hostnames.$maxRemoteSize(int): 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): Override for the default cURL options; null uses CURLOPT_DEFAULT.$fixedCurlOpts(array<int,bool|int|string|callable|resource>|null): Override for the fixed cURL options; null uses CURLOPT_FIXED.$allowedPaths(string[]): Allowlist of trusted file paths.$caseSensitivePaths(bool|null): Override for path case-sensitivity: null = auto-detect, true = case-sensitive, false = case-insensitive.
Throws:
- Exception: when $maxRemoteSize is not positive.
Source: src/File.php:158
fileGetContents()
Reads entire file into a string.
The file can be also an URL.
public fileGetContents(string $file): string
Parameters:
$file(string): Name of the file or URL to read.
Returns: string
Throws:
- Exception: in case of error.
Source: src/File.php:366
fopenLocal()
Wrapper to use fopen only with local files.
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.
Returns: resource: Returns a file pointer resource on success.
Throws:
- Exception: in case of error.
Source: src/File.php:278
fReadInt()
Read a 4-byte (32 bit) integer from file.
public fReadInt(resource $resource): int
Parameters:
$resource(resource): A file system pointer resource that is typically created using \fopen().
Returns: int: 4-byte integer.
Throws:
- Exception: in case of error.
Source: src/File.php:306
getAltFilePaths()
Returns an array of possible alternative file paths or URLs
public getAltFilePaths(string $file): list<string>
Parameters:
$file(string): Name of the file or URL to read.
Returns: list<string>: List of possible alternative file paths or URLs.
Source: src/File.php:832
getFileData()
Reads entire file into a string.
The file can be also an URL.
public getFileData(string $file): string|false
Parameters:
$file(string): Name of the file or URL to read.
Returns: string|false: File content or FALSE in case the file is unreadable
Throws:
- Exception: in case the remote transfer is aborted due to max size.
Source: src/File.php:389
getLocalFileData()
Reads entire local file into a string.
public getLocalFileData(string $file): string|false
Parameters:
$file(string): Name of the file to read.
Returns: string|false: File content, or FALSE when the path is not allowlisted, not a valid local path, or unreadable.
Source: src/File.php:408
getMaxRemoteSize()
Get the maximum size (in bytes) for remote file reads.
public getMaxRemoteSize(): int
Returns: int
Source: src/File.php:262
getUrlData()
Reads entire remote file into a string using CURL.
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.
public getUrlData(string $url): string|false
Parameters:
$url(string): URL to read.
Returns: string|false: Remote content, or FALSE when the URL is not allowlisted, the response is an unfollowed redirect, or the transfer fails.
Throws:
- Exception: if the remote transfer is aborted due to max size, or a configured cURL option is not valid or cannot be applied.
Source: src/File.php:678
isAllowedFile()
Validate a local file path against the configured $allowedPaths allowlist.
By-value counterpart of isValidFile(), callable with a literal or any other expression and leaving the argument untouched.
public isAllowedFile(string $file): bool
Parameters:
$file(string): File path to validate.
Returns: bool
Source: src/File.php:1128
isAllowedUrl()
Validate an HTTP(S) URL against the configured host allowlist.
By-value counterpart of isValidURL(), callable with a literal or any other expression and leaving the argument untouched.
public isAllowedUrl(string $url): bool
Parameters:
$url(string): URL to validate.
Returns: bool
Source: src/File.php:1115
isValidFile()
Validate a local file path against the configured $allowedPaths allowlist.
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.
public isValidFile(string &$file): bool
Parameters:
$file(string): File path to validate.
Returns: bool
Source: src/File.php:1415
isValidURL()
Validate an HTTP(S) URL against the configured host allowlist.
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.
public isValidURL(string &$url): bool
Parameters:
$url(string): URL to validate.
Returns: bool
Source: src/File.php:1048
resolveLocalPath()
Resolve a local file path against explicit base directories.
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.
public resolveLocalPath(string $file, string[] $baseDirs = []): string
Parameters:
$file(string): Local file path to resolve.$baseDirs(string[]): Candidate base directories checked in order.
Returns: string
Source: src/File.php:856
rfRead()
Binary-safe file read.
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.
public rfRead(?resource $resource, int $length): string
Parameters:
$resource(?resource): A file system pointer resource that is typically created using \fopen().$length(int): Number of bytes to read; must be positive.
Returns: string
Throws:
- Exception: when $length is not positive, or in case of a read error.
Source: src/File.php:329
setAllowedHosts()
Set the allowlist of trusted hostnames.
public setAllowedHosts(string[] $allowedHosts): static
Parameters:
$allowedHosts(string[]): Trusted hostname strings.
Returns: static
Source: src/File.php:213
setAllowedPaths()
Set the allowlist of trusted file paths.
public setAllowedPaths(string[] $allowedPaths): static
Parameters:
$allowedPaths(string[]): Trusted file path strings.
Returns: static
Source: src/File.php:224
setCaseSensitivePaths()
Override how path case-sensitivity is determined for allowlist matching.
public setCaseSensitivePaths(bool|null $caseSensitivePaths): static
Parameters:
$caseSensitivePaths(bool|null): null = auto-detect per platform/volume, true = case-sensitive, false = case-insensitive.
Returns: static
Source: src/File.php:236
setCurlOpts()
Set custom cURL options.
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.
Returns: static
Source: src/File.php:202
setMaxRemoteSize()
Set the maximum size (in bytes) for remote file reads.
public setMaxRemoteSize(int $maxRemoteSize): static
Parameters:
$maxRemoteSize(int): Maximum allowed bytes; must be positive.
Returns: static
Throws:
- Exception: when $maxRemoteSize is not positive.
Source: src/File.php:249