Documentation

File extends Io
in package

Maho

Abstract I/O class with security utilities for path validation

Constants

ALLOWED_IMAGES_EXTENSIONS : array<string|int, string> = ['webp', 'avif', 'jpg', 'jpeg', 'png', 'gif', '...
GREP_DIRS : mixed = 'dirs_only': Used to grep ls() output
GREP_FILES : mixed = 'files_only': Used to grep ls() output

Properties

$_allowCreateFolders : bool: If this variable is set to TRUE, our library will be able to automatically create non-existent directories.
$_cwd : string: Use virtual current working directory for application integrity
$_iwd : string: Save initial working directory
$_streamChmod : int: Stream mode chmod
$_streamException : Exception
$_streamFileName : string: Stream mode filename
$_streamHandler : resource|null: Stream open file pointer
$_streamLocked : bool: Lock file

Methods

__construct() : mixed
cd() : bool: Change current working directory
checkAndCreateFolder() : bool: Check and create if not exists folder
chmod() : bool: Change mode of a directory or a file
close() : bool: Close a connection
cp() : bool: Copy a file
createDestinationDir() : bool: Create destination folder
destruct() : void: stream close on shutdown
dirname() : mixed
dirsep() : string: Retrieve directory separator in context of io resource
fileExists() : mixed
filePutContent() : int: File put content wrapper
getCleanPath() : string
getDestinationFolder() : mixed
getFilteredPath() : string: Replace full path to relative
getImageSize() : array<int|string, mixed>|false: Safe wrapper for getimagesize() that prevents phar:// deserialization
getImageSizeOnMount() : array<int|string, mixed>|false: The getimagesize() data of the file at $path on $mount, or false when it cannot be read.
getPathWithinDir() : string|null: Resolve $path inside $baseDir and return the canonical absolute path, or null when it escapes.
getPathWithinMount() : string|null: The mount path of $file below $directory, or null when $file is empty, holds a null byte, or leaves $directory through a dot segment. A leading slash does not make $file absolute: stored names such as /m/a/file.pdf start with one, so $file always stays below $directory.
getStreamException() : Exception: Retrieve stream methods exception
getStreamHandler() : mixed
isWriteable() : mixed
ls() : array<string|int, mixed>: Get list of cwd subdirectories and files
mkdir() : bool: Create a directory
mv() : bool: Rename or move a directory or a file
open() : bool: Open a connection
pwd() : string: Get current working directory
read() : bool|string: Read a file to result, file or stream
rm() : bool: Delete a file
rmdir() : bool: Delete a directory
rmdirRecursive() : bool: Delete a directory recursively
setAllowCreateFolders() : $this: Used to set {@link _allowCreateFolders} value
streamClose() : bool: Close an open file pointer Set chmod on a file
streamLock() : bool: Lock file
streamOpen() : bool: Open file in stream mode For set folder for file use open method
streamRead() : bool|string: Binary-safe file read
streamReadCsv() : array<string|int, mixed>|false|null: Gets line from file pointer and parse for CSV fields
streamStat() : array<string|int, mixed>|bool: Retrieve open file statistic
streamUnlock() : bool: Unlock file
streamWrite() : bool|int: Binary-safe file write
streamWriteCsv() : bool|int: Format line as CSV and write to file pointer
write() : int|bool: Write a file from string, file or stream
_assertInsideCwd() : void: Refuse a null byte, a ".." segment, and a destination outside the open working directory
_checkSrcIsFile() : bool: Check source is file
_getFileOwner() : string: Get file owner
_isFilenameWriteable() : bool: Check filename is writeable If filename not exist check dirname writeable
_isValidSource() : bool: Check source is valid
_parsePermissions() : string: Convert integer permissions format into human readable

ALLOWED_IMAGES_EXTENSIONS


    public
        array<string|int, string>
    ALLOWED_IMAGES_EXTENSIONS
    = ['webp', 'avif', 'jpg', 'jpeg', 'png', 'gif', 'bmp']

GREP_DIRS

Used to grep ls() output


    public
        mixed
    GREP_DIRS
    = 'dirs_only'

GREP_FILES

Used to grep ls() output


    public
        mixed
    GREP_FILES
    = 'files_only'

$_allowCreateFolders

If this variable is set to TRUE, our library will be able to automatically create non-existent directories.


        protected
            bool
    $_allowCreateFolders
     = false

$_cwd

Use virtual current working directory for application integrity


        protected
            string
    $_cwd

$_iwd

Save initial working directory


        protected
            string
    $_iwd

$_streamChmod

Stream mode chmod


        protected
            int
    $_streamChmod

$_streamException


        protected
            Exception
    $_streamException

$_streamFileName

Stream mode filename


        protected
            string
    $_streamFileName

$_streamHandler

Stream open file pointer


        protected
            resource|null
    $_streamHandler

$_streamLocked

Lock file


        protected
            bool
    $_streamLocked
     = false

__construct()


    public
                    __construct() : mixed

cd()

Change current working directory


    public
                    cd(string $dir) : bool

Parameters

$dir : string

Return values

bool

checkAndCreateFolder()

Check and create if not exists folder


    public
                    checkAndCreateFolder(string $folder[, int $mode = 0777 ]) : bool

Parameters

$folder : string
$mode : int = 0777

Return values

bool

chmod()

Change mode of a directory or a file


    public
                    chmod(string $filename, int $mode) : bool

Parameters

$filename : string
$mode : int

#[Override]

Return values

bool

close()

Close a connection


    public
                    close() : bool

#[Override]

Return values

bool

cp()

Copy a file


    public
                    cp(string $src, string $dest) : bool

Parameters

$src : string
$dest : string

Return values

bool

createDestinationDir()

Create destination folder


    public
                    createDestinationDir(string $path) : bool

Parameters

$path : string

Return values

bool

destruct()

stream close on shutdown


    public
                    destruct() : void

dirname()


    public
                    dirname(mixed $file) : mixed

Parameters

$file : mixed

dirsep()

Retrieve directory separator in context of io resource


    public
                    dirsep() : string

#[Override]

Return values

string

fileExists()


    public
                    fileExists(mixed $file[, mixed $onlyFile = true ]) : mixed

Parameters

$file : mixed
$onlyFile : mixed = true

filePutContent()

File put content wrapper


    public
                    filePutContent(string $filename, string|resource $src) : int

Parameters

$filename : string
$src : string|resource

Return values

int

getCleanPath()


    public
                    getCleanPath(mixed $path) : string

Parameters

$path : mixed

Return values

string

getDestinationFolder()


    public
                    getDestinationFolder(mixed $filepath) : mixed

Parameters

$filepath : mixed

getFilteredPath()

Replace full path to relative


    public
                    getFilteredPath(string $path) : string

Parameters

$path : string

Return values

string

getImageSize()

Safe wrapper for getimagesize() that prevents phar:// deserialization


    public
            static        getImageSize(string $filename) : array<int|string, mixed>|false

Parameters

$filename : string: The file path to check

Return values

array<int|string, mixed>|false —

Image size info or false on failure/unsafe path

getImageSizeOnMount()

The getimagesize() data of the file at $path on $mount, or false when it cannot be read.


    public
            static        getImageSizeOnMount(Mount $mount, string $path[, array<int, string> $cacheTags = [] ]) : array<int|string, mixed>|false

A remote mount reads the file once and keeps the data in the cache for a year, so a page render does not download it.

Parameters

$mount : Mount
$path : string
$cacheTags : array<int, string> = []

Return values

array<int|string, mixed>|false

getPathWithinDir()

Resolve $path inside $baseDir and return the canonical absolute path, or null when it escapes.


    public
            static        getPathWithinDir(string $baseDir, string $path) : string|null

A relative $path is joined to $baseDir; an absolute one must already lie inside it. Dot segments and backslashes are collapsed before the check, stream wrappers and null bytes are refused, and the deepest existing ancestor is compared through realpath() so a symlink cannot lead outside the base directory. The path itself does not need to exist.

Parameters

$baseDir : string
$path : string

Return values

string|null

getPathWithinMount()

The mount path of $file below $directory, or null when $file is empty, holds a null byte, or leaves $directory through a dot segment. A leading slash does not make $file absolute: stored names such as /m/a/file.pdf start with one, so $file always stays below $directory.


    public
            static        getPathWithinMount(Mount $mount, string $directory, string $file) : string|null

Use it on every name that a request or a database row supplies before a read, a write or a delete on a mount.

A local mount applies getPathWithinDir() on the disk, so a symlink inside $directory cannot lead outside it. A remote mount has only the key, so it applies the canonical containment on that.

Parameters

$mount : Mount
$directory : string
$file : string

Return values

string|null

getStreamException()

Retrieve stream methods exception


    public
                    getStreamException() : Exception

Return values

Exception

getStreamHandler()


    public
                    getStreamHandler() : mixed

isWriteable()


    public
                    isWriteable(mixed $path) : mixed

Parameters

$path : mixed

ls()

Get list of cwd subdirectories and files


    public
                    ls([File $grep = null ]) : array<string|int, mixed>

Suggestions (from moshe):

Use filemtime instead of filectime for performance
Change $grep to $flags and use binary flags
- LS_DIRS = 1
- LS_FILES = 2
- LS_ALL = 3

Parameters

$grep : File = null: const

Return values

array<string|int, mixed>

mkdir()

Create a directory


    public
                    mkdir(string $dir[, int $mode = 0777 ][, bool $recursive = true ]) : bool

Parameters

$dir : string
$mode : int = 0777
$recursive : bool = true

#[Override]

Return values

bool

mv()

Rename or move a directory or a file


    public
                    mv(string $src, string $dest) : bool

Parameters

$src : string
$dest : string

#[Override]

Return values

bool

open()

Open a connection


    public
                    open([array<string|int, mixed> $args = [] ]) : bool

Possible arguments:

path default current path

Parameters

$args : array<string|int, mixed> = []

#[Override]

Return values

bool

pwd()

Get current working directory


    public
                    pwd() : string

#[Override]

Return values

string

read()

Read a file to result, file or stream


    public
                    read(string $filename[, string|resource $dest = null ]) : bool|string

If $dest is null the output will be returned. Otherwise it will be saved to the file or stream and operation result is returned.

Parameters

$filename : string
$dest : string|resource = null

#[Override]

Return values

bool|string

rm()

Delete a file


    public
                    rm(string $filename) : bool

Parameters

$filename : string

#[Override]

Return values

bool

rmdir()

Delete a directory


    public
                    rmdir(string $dir[, mixed $recursive = false ]) : bool

Parameters

$dir : string
$recursive : mixed = false

#[Override]

Return values

bool

rmdirRecursive()

Delete a directory recursively


    public
            static        rmdirRecursive(string $dir[, bool $recursive = true ]) : bool

Parameters

$dir : string
$recursive : bool = true

Return values

bool

setAllowCreateFolders()

Used to set {@link _allowCreateFolders} value


    public
                    setAllowCreateFolders(bool $flag) : $this

Parameters

$flag : bool

Return values

$this

streamClose()

Close an open file pointer Set chmod on a file


    public
                    streamClose() : bool

Return values

bool

streamLock()

Lock file


    public
                    streamLock([bool $exclusive = true ][, bool $blocking = true ]) : bool

Parameters

$exclusive : bool = true
$blocking : bool = true

Return values

bool

streamOpen()

Open file in stream mode For set folder for file use open method


    public
                    streamOpen(string $fileName[, string $mode = 'w+' ][, mixed $chmod = 0666 ]) : bool

Parameters

$fileName : string
$mode : string = 'w+'
$chmod : mixed = 0666

Return values

bool

streamRead()

Binary-safe file read


    public
                    streamRead([int $length = 1024 ]) : bool|string

Parameters

$length : int = 1024

Return values

bool|string

streamReadCsv()

Gets line from file pointer and parse for CSV fields


    public
                    streamReadCsv([mixed $delimiter = ',' ][, mixed $enclosure = '"' ]) : array<string|int, mixed>|false|null

Parameters

$delimiter : mixed = ','
$enclosure : mixed = '"'

Return values

array<string|int, mixed>|false|null

streamStat()

Retrieve open file statistic


    public
                    streamStat([string $part = null ][, mixed $default = null ]) : array<string|int, mixed>|bool

Parameters

$part : string = null: the part of statistic
$default : mixed = null: default value for part

Return values

array<string|int, mixed>|bool

streamUnlock()

Unlock file


    public
                    streamUnlock() : bool

Return values

bool

streamWrite()

Binary-safe file write


    public
                    streamWrite(string $str) : bool|int

Parameters

$str : string

Return values

bool|int

streamWriteCsv()

Format line as CSV and write to file pointer


    public
                    streamWriteCsv(array<string|int, mixed> $row[, string $delimiter = ',' ][, string $enclosure = '"' ]) : bool|int

Parameters

$row : array<string|int, mixed>
$delimiter : string = ','
$enclosure : string = '"'

Return values

bool|int

write()

Write a file from string, file or stream


    public
                    write(string $filename, string|resource $src[, int $mode = null ]) : int|bool

Parameters

$filename : string
$src : string|resource
$mode : int = null

Return values

int|bool

_assertInsideCwd()

Refuse a null byte, a ".." segment, and a destination outside the open working directory


    protected
                    _assertInsideCwd(string $filename) : void

Parameters

$filename : string

_checkSrcIsFile()

Check source is file


    protected
                    _checkSrcIsFile(string $src) : bool

Parameters

$src : string

Return values

bool

_getFileOwner()

Get file owner


    protected
                    _getFileOwner(string $filename) : string

Parameters

$filename : string

Return values

string

_isFilenameWriteable()

Check filename is writeable If filename not exist check dirname writeable


    protected
                    _isFilenameWriteable(string $filename) : bool

Parameters

$filename : string

Return values

bool

_isValidSource()

Check source is valid


    protected
                    _isValidSource(string|resource $src) : bool

Parameters

$src : string|resource

Return values

bool

_parsePermissions()

Convert integer permissions format into human readable


    protected
                    _parsePermissions(int $mode) : string

Parameters

$mode : int

Return values

string

File extends Io in package Maho

Table of Contents

Constants

Properties

Methods

Constants

ALLOWED_IMAGES_EXTENSIONS

GREP_DIRS

Tags

GREP_FILES

Tags

Properties

$_allowCreateFolders

Tags

Attributes

$_cwd

$_iwd

$_streamChmod

$_streamException

$_streamFileName

$_streamHandler

$_streamLocked

Methods

__construct()

cd()

Parameters

Tags

Attributes

Return values

checkAndCreateFolder()

Parameters

Tags

Return values

chmod()

Parameters

Attributes

Return values

close()

Attributes

Return values

cp()

Parameters

Return values

createDestinationDir()

Parameters

Return values

destruct()

dirname()

Parameters

dirsep()

Attributes

Return values

fileExists()

Parameters

filePutContent()

Parameters

Return values

getCleanPath()

Parameters

Return values

getDestinationFolder()

Parameters

getFilteredPath()

Parameters

Return values

getImageSize()

Parameters

Return values

getImageSizeOnMount()

Parameters

Return values

getPathWithinDir()

Parameters

Return values

getPathWithinMount()

Parameters

Return values

getStreamException()

Return values

getStreamHandler()

File extends Io
in package

Maho