SplFileObject

class SplFileObject extends SplFileInfo implements RecursiveIterator, SeekableIterator (View source)

The SplFileObject class offers an object oriented interface for a file.

Constants

DROP_NEW_LINE

Drop newlines at the end of a line.
READ_AHEAD

Read on rewind/next.
SKIP_EMPTY

Skip empty lines in the file. This requires the {READ_AHEAD} flag to work as expected.
READ_CSV

Read lines as CSV rows.

Methods

__construct(string $filename, string $mode = 'r', bool $useIncludePath = false, resource $context = null)

Construct a new file object.

string
getPath()

Gets the path without filename

from  SplFileInfo
string
getFilename()

Gets the filename

from  SplFileInfo
string
getExtension()

Gets the file extension

from  SplFileInfo
string
getBasename(string $suffix = '')

Gets the base name of the file

from  SplFileInfo
string
getPathname()

Gets the path to the file

from  SplFileInfo
int|false
getPerms()

Gets file permissions

from  SplFileInfo
int|false
getInode()

Gets the inode for the file

from  SplFileInfo
int|false
getSize()

Gets file size

from  SplFileInfo
int|false
getOwner()

Gets the owner of the file

from  SplFileInfo
int|false
getGroup()

Gets the file group

from  SplFileInfo
int|false
getATime()

Gets last access time of the file

from  SplFileInfo
int|false
getMTime()

Gets the last modified time

from  SplFileInfo
int|false
getCTime()

Gets the inode change time

from  SplFileInfo
string|false
getType()

Gets file type

from  SplFileInfo
bool
isWritable()

Tells if the entry is writable

from  SplFileInfo
bool
isReadable()

Tells if file is readable

from  SplFileInfo
bool
isExecutable()

Tells if the file is executable

from  SplFileInfo
bool
isFile()

Tells if the object references a regular file

from  SplFileInfo
bool
isDir()

Tells if the file is a directory

from  SplFileInfo
bool
isLink()

Tells if the file is a link

from  SplFileInfo
string|false
getLinkTarget()

Gets the target of a link

from  SplFileInfo
string|false
getRealPath()

Gets absolute path to file

from  SplFileInfo
SplFileInfo
getFileInfo(T> $class = null)

Gets an SplFileInfo object for the file

from  SplFileInfo
SplFileInfo|null
getPathInfo(T> $class = null)

Gets an SplFileInfo object for the path

from  SplFileInfo
SplFileObject
openFile(string $mode = 'r', bool $useIncludePath = false, resource $context = null)

Gets an SplFileObject object for the file

from  SplFileInfo
void
setFileClass(T> $class = SplFileObject::class)

Sets the class name used with SplFileInfo::openFile

from  SplFileInfo
void
setInfoClass(T> $class = SplFileInfo::class)

Sets the class used with getFileInfo and getPathInfo

from  SplFileInfo
string
__toString()

Alias of SplFileObject::current

void
_bad_state_ex()

No description

from  SplFileInfo
__wakeup()

No description

from  SplFileInfo
array
__debugInfo()

No description

from  SplFileInfo
void
rewind()

Rewind the file to the first line

bool
eof()

Reached end of file

bool
valid()

Not at EOF

string
fgets()

Gets line from file

string|false
fread(int $length)

Read from file

array|false|null
fgetcsv(string $separator = ",", string $enclosure = "\"", string $escape = "\\")

Gets line from file and parse as CSV fields

int|false
fputcsv(array $fields, string $separator = ',', string $enclosure = '"', string $escape = "\\", string $eol = PHP_EOL)

Write a field array as a CSV line

void
setCsvControl(string $separator = ",", string $enclosure = "\"", string $escape = "\\")

Set the delimiter and enclosure character for CSV

array
getCsvControl()

Get the delimiter and enclosure character for CSV

bool
flock(int $operation, int $wouldBlock = null)

Portable file locking

bool
fflush()

Flushes the output to the file

int|false
ftell()

Return current file position

int
fseek(int $offset, int $whence = SEEK_SET)

Seek to a position

string|false
fgetc()

Gets character from file

int
fpassthru()

Output all remaining data on a file pointer

string|false
fgetss(string $allowable_tags = null)

Gets line from file and strip HTML tags

array|int|null
fscanf(string $format, mixed ...$vars)

Parses input from file according to a format

int|false
fwrite(string $data, int $length = 0)

Write to file

array
fstat()

Gets information about the file

bool
ftruncate(int $size)

Truncates the file to a given length

mixed
current()

Retrieve current line of file

mixed
key()

Get line number

void
next()

Read next line

void
setFlags(int $flags)

Sets flags for the SplFileObject

int
getFlags()

Gets flags for the SplFileObject

void
setMaxLineLen(int $maxLength)

Set maximum line length

int
getMaxLineLen()

Get maximum line length

bool
hasChildren()

SplFileObject does not have children

RecursiveIterator|null
getChildren()

No purpose

void
seek(int $line)

Seek to specified line

string
getCurrentLine()

Alias of SplFileObject::fgets

Details

at line 650
__construct(string $filename, string $mode = 'r', bool $useIncludePath = false, resource $context = null)

Construct a new file object.

Parameters

string $filename
string $mode

[optional] The mode in which to open the file. See {\fopen} for a list of allowed modes.
bool $useIncludePath

[optional] Whether to search in the include_path for filename
resource $context

[optional] A valid context resource created with {\stream_context_create}

Exceptions

RuntimeException
LogicException

in SplFileInfo at line 30
string getPath()

Since: 5.1.2

Gets the path without filename

Return Value

string

the path to the file.

in SplFileInfo at line 39
string getFilename()

Since: 5.1.2

Gets the filename

Return Value

string

The filename.

in SplFileInfo at line 49
string getExtension()

Since: 5.3.6

Gets the file extension

Return Value

string

a string containing the file extension, or an empty string if the file has no extension.

in SplFileInfo at line 61
string getBasename(string $suffix = '')

Since: 5.2.2

Gets the base name of the file

Parameters

string $suffix

[optional]

Optional suffix to omit from the base name returned.

Return Value

string

the base name without path information.

in SplFileInfo at line 70
string getPathname()

Since: 5.1.2

Gets the path to the file

Return Value

string

The path to the file.

in SplFileInfo at line 79
int|false getPerms()

Since: 5.1.2

Gets file permissions

Return Value

int|false

The file permissions on success, or FALSE on failure.

in SplFileInfo at line 89
int|false getInode()

Since: 5.1.2

Gets the inode for the file

Return Value

int|false

The inode number for the filesystem object on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 99
int|false getSize()

Since: 5.1.2

Gets file size

Return Value

int|false

The filesize in bytes on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 109
int|false getOwner()

Since: 5.1.2

Gets the owner of the file

Return Value

int|false

The owner id in numerical format on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 119
int|false getGroup()

Since: 5.1.2

Gets the file group

Return Value

int|false

The group id in numerical format on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 129
int|false getATime()

Since: 5.1.2

Gets last access time of the file

Return Value

int|false

The time the file was last accessed on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 138
int|false getMTime()

Since: 5.1.2

Gets the last modified time

Return Value

int|false

The last modified time for the file, in a Unix timestamp on success, or FALSE on failure.

in SplFileInfo at line 148
int|false getCTime()

Since: 5.1.2

Gets the inode change time

Return Value

int|false

The last change time, in a Unix timestamp on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 160
string|false getType()

Since: 5.1.2

Gets file type

Return Value

string|false

A string representing the type of the entry. May be one of file, link, dir, block, fifo, char, socket, or unknown, or FALSE on failure. May be one of file, link, or dir

Exceptions

RuntimeException

in SplFileInfo at line 169
bool isWritable()

Since: 5.1.2

Tells if the entry is writable

Return Value

bool

true if writable, false otherwise;

in SplFileInfo at line 178
bool isReadable()

Since: 5.1.2

Tells if file is readable

Return Value

bool

true if readable, false otherwise.

in SplFileInfo at line 187
bool isExecutable()

Since: 5.1.2

Tells if the file is executable

Return Value

bool

true if executable, false otherwise.

in SplFileInfo at line 196
bool isFile()

Since: 5.1.2

Tells if the object references a regular file

Return Value

bool

true if the file exists and is a regular file (not a link), false otherwise.

in SplFileInfo at line 205
bool isDir()

Since: 5.1.2

Tells if the file is a directory

Return Value

bool

true if a directory, false otherwise.
Since: 5.1.2

Tells if the file is a link

Return Value

bool

true if the file is a link, false otherwise.

in SplFileInfo at line 224
string|false getLinkTarget()

Since: 5.2.2

Gets the target of a link

Return Value

string|false

The target of the filesystem link on success, or FALSE on failure.

Exceptions

RuntimeException

in SplFileInfo at line 233
string|false getRealPath()

Since: 5.2.2

Gets absolute path to file

Return Value

string|false

the path to the file, or FALSE if the file does not exist.

in SplFileInfo at line 246
SplFileInfo getFileInfo(T> $class = null)

Since: 5.1.2

Gets an SplFileInfo object for the file

Parameters

T> $class

[optional]

Name of an SplFileInfo derived class to use.

Return Value

SplFileInfo

An SplFileInfo object created for the file.

in SplFileInfo at line 259
SplFileInfo|null getPathInfo(T> $class = null)

Since: 5.1.2

Gets an SplFileInfo object for the path

Parameters

T> $class

[optional]

Name of an SplFileInfo derived class to use.

Return Value

SplFileInfo|null

A SplFileInfo object for the parent path of the file on success, or NULL on failure.

in SplFileInfo at line 278
SplFileObject openFile(string $mode = 'r', bool $useIncludePath = false, resource $context = null)

Since: 5.1.2

Gets an SplFileObject object for the file

Parameters

string $mode

[optional]

The mode for opening the file. See the fopen documentation for descriptions of possible modes. The default is read only.

bool $useIncludePath

[optional]

resource $context

[optional]

Return Value

SplFileObject

The opened file as an SplFileObject object.

Exceptions

RuntimeException

in SplFileInfo at line 295
void setFileClass(T> $class = SplFileObject::class)

Since: 5.1.2

Sets the class name used with SplFileInfo::openFile

Parameters

T> $class

[optional]

The class name to use when openFile() is called.

Return Value

void

in SplFileInfo at line 308
void setInfoClass(T> $class = SplFileInfo::class)

Since: 5.1.2

Sets the class used with getFileInfo and getPathInfo

Parameters

T> $class

[optional]

The class name to use.

Return Value

void

at line 1049
string __toString()

Alias of SplFileObject::current

Return Value

string

Returns string representation of the object that implements this interface (and/or "__toString" magic method).

in SplFileInfo at line 320
final void _bad_state_ex()

No description

Return Value

void

in SplFileInfo at line 323
__wakeup()

No description

in SplFileInfo at line 329
array __debugInfo()

Since: 7.4

No description

Return Value

array

at line 664
void rewind()

Rewind the file to the first line

Return Value

void

Any returned value is ignored.

Exceptions

RuntimeException

at line 672
bool eof()

Reached end of file

Return Value

bool

true if file is at EOF, false otherwise.

at line 680
bool valid()

Not at EOF

Return Value

bool

The return value will be casted to boolean and then evaluated. Returns true on success or false on failure.

at line 690
string fgets()

Gets line from file

Return Value

string

a string containing the next line from the file.

Exceptions

RuntimeException

at line 702
string|false fread(int $length)

Since: 5.5.11

Read from file

Parameters

int $length

The number of bytes to read.

Return Value

string|false

returns the string read from the file or FALSE on failure.

at line 724
array|false|null fgetcsv(string $separator = ",", string $enclosure = "\"", string $escape = "\\")

Gets line from file and parse as CSV fields

Parameters

string $separator

[optional]

The field delimiter (one character only). Defaults as a comma or the value set using SplFileObject::setCsvControl.

string $enclosure

[optional]

The field enclosure character (one character only). Defaults as a double quotation mark or the value set using SplFileObject::setCsvControl.

string $escape

[optional]

The escape character (one character only). Defaults as a backslash () or the value set using SplFileObject::setCsvControl.

Return Value

array|false|null

an indexed array containing the fields read, or false on error.

A blank line in a CSV file will be returned as an array comprising a single null field unless using SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE, in which case empty lines are skipped.

at line 746
int|false fputcsv(array $fields, string $separator = ',', string $enclosure = '"', string $escape = "\\", string $eol = PHP_EOL)

Since: 5.4

Write a field array as a CSV line

Parameters

array $fields

An array of values
string $separator

[optional]

The field delimiter (one character only). Defaults as a comma or the value set using SplFileObject::setCsvControl.

string $enclosure

[optional]

The field enclosure character (one character only). Defaults as a double quotation mark or the value set using SplFileObject::setCsvControl.

string $escape

The optional escape parameter sets the escape character (one character only).
string $eol

Return Value

int|false

Returns the length of the written string or FALSE on failure.

at line 769
void setCsvControl(string $separator = ",", string $enclosure = "\"", string $escape = "\\")

Set the delimiter and enclosure character for CSV

Parameters

string $separator

[optional]

The field delimiter (one character only).

string $enclosure

[optional]

The field enclosure character (one character only).

string $escape

[optional]

The field escape character (one character only).

Return Value

void

at line 781
array getCsvControl()

Get the delimiter and enclosure character for CSV

Return Value

array

an indexed array containing the delimiter and enclosure character.

at line 796
bool flock(int $operation, int $wouldBlock = null)

Portable file locking

Parameters

int $operation

operation is one of the following: LOCK_SH to acquire a shared lock (reader).

int $wouldBlock

[optional]

Set to 1 if the lock would block (EWOULDBLOCK errno condition).

Return Value

bool

true on success or false on failure.

at line 804
bool fflush()

Flushes the output to the file

Return Value

bool

true on success or false on failure.

at line 812
int|false ftell()

Return current file position

Return Value

int|false

the position of the file pointer as an integer, or false on error.

at line 834
int fseek(int $offset, int $whence = SEEK_SET)

Seek to a position

Parameters

int $offset

The offset. A negative value can be used to move backwards through the file which is useful when SEEK_END is used as the whence value.

int $whence

[optional]

whence values are: SEEK_SET - Set position equal to offset bytes. SEEK_CUR - Set position to current location plus offset. SEEK_END - Set position to end-of-file plus offset.

If whence is not specified, it is assumed to be SEEK_SET.

Return Value

int

0 if the seek was successful, -1 otherwise. Note that seeking past EOF is not considered an error.

at line 845
string|false fgetc()

Gets character from file

Return Value

string|false

a string containing a single character read from the file or false on EOF.

at line 854
int fpassthru()

Output all remaining data on a file pointer

Return Value

int

the number of characters read from handle and passed through to the output.

at line 868
string|false fgetss(string $allowable_tags = null)

Gets line from file and strip HTML tags

Parameters

string $allowable_tags

[optional]

You can use the optional third parameter to specify tags which should not be stripped.

Return Value

string|false

a string containing the next line of the file with HTML and PHP code stripped, or false on error.

at line 885
array|int|null fscanf(string $format, mixed ...$vars)

Parses input from file according to a format

Parameters

string $format

The specified format as described in the sprintf documentation.

mixed ...$vars

[optional]

The optional assigned values.

Return Value

array|int|null

If only one parameter is passed to this method, the values parsed will be returned as an array. Otherwise, if optional parameters are passed, the function will return the number of assigned values. The optional parameters must be passed by reference.

at line 905
int|false fwrite(string $data, int $length = 0)

Write to file

Parameters

string $data

The string to be written to the file.

int $length

[optional]

If the length argument is given, writing will stop after length bytes have been written or the end of string is reached, whichever comes first.

Return Value

int|false

the number of bytes written, or 0 (false since 7.4) on error.

at line 918
array fstat()

Gets information about the file

Return Value

array

an array with the statistics of the file; the format of the array is described in detail on the stat manual page.

at line 935
bool ftruncate(int $size)

Truncates the file to a given length

Parameters

int $size

The size to truncate to.

If size is larger than the file it is extended with null bytes.

If size is smaller than the file, the extra data will be lost.

Return Value

bool

true on success or false on failure.

at line 943
mixed current()

Retrieve current line of file

Return Value

mixed

Can return any type.

at line 951
mixed key()

Get line number

Return Value

mixed

TKey on success, or null on failure.

at line 959
void next()

Read next line

Return Value

void

Any returned value is ignored.

at line 972
void setFlags(int $flags)

Sets flags for the SplFileObject

Parameters

int $flags

Bit mask of the flags to set. See SplFileObject constants for the available flags.

Return Value

void

at line 980
int getFlags()

Gets flags for the SplFileObject

Return Value

int

an integer representing the flags.

at line 993
void setMaxLineLen(int $maxLength)

Set maximum line length

Parameters

int $maxLength

The maximum length of a line.

Return Value

void

Exceptions

DomainException

at line 1002
int getMaxLineLen()

Get maximum line length

Return Value

int

the maximum line length if one has been set with SplFileObject::setMaxLineLen, default is 0.

at line 1011
bool hasChildren()

Since: 5.1.2

SplFileObject does not have children

Return Value

bool

true if the current entry can be iterated over, otherwise returns false.

at line 1020
RecursiveIterator|null getChildren()

No purpose

Return Value

RecursiveIterator|null

An iterator for the current entry.

at line 1033
void seek(int $line)

Seek to specified line

Parameters

int $line

The zero-based line number to seek to.

Return Value

void

Exceptions

LogicException

at line 1042
string getCurrentLine()

Since: 5.1.2

Alias of SplFileObject::fgets

Return Value

string

Returns a string containing the next line from the file.