dgifford/text-file

Class providing methods for editing text files on a line-by-line basis.

Text File Edit

Class for manipulating text files line by line., _(*1)

Designed for editing/ creating text files where sections or lines are easily distinguished by the lines around them., _(*2)

For example, configuration files like .htaccess where sections may be defined by comments or if statements., _(*3)

Instantiation

The object can be initiated by providing the constructor with:, _(*4)

• A valid file path
• A string
• An array of strings (lines)

$text = new TextFile( 'foo.txt' );

$text = new TextFile( "line 1\nline 2\nline 3\nline 4" );

$text = new TextFile( ["line 1", "line 2", "line 3", "line 4"] );

Or, by using the load method:, _(*5)

$text = new TextFile();

$text->load( 'foo.txt' );

$text->load( "line 1\nline 2\nline 3\nline 4" );

$text->load( ["line 1", "line 2", "line 3", "line 4"] );

Array Access

The class implements array access and array iterator, so lines can be accessed using array notation and a foreach loop:, _(*6)

$text->load( 'foo.txt' );

// Output the first line
echo $text[0];

// Iterate over each line
foreach( $text as $index => $line )
{
    ...
}

Editing

Lines can be edited directly using array access:, _(*7)

$text->load( 'foo.txt' );

// Change the first line
echo $text[0] = 'This is the first line';

// Delete the first line
unset( $text[0] );

The following methods provide more flexibility when editing., _(*8)

delete

Deletes all lines: $text->delete(), _(*9)

Delete all lines containing the string 'bar': $text->delete( 'bar' ), _(*10)

Deleting blocks of lines can be achieved by providing two strings to the method to identify the start and end lines., _(*11)

However, lines will only be deleted if the section is unique (start and end lines only occur once) and start line is before the end line., _(*12)

For example, to delete the block of lines where the first line contains 'foo' and the last line contains 'bar':, _(*13)

$result = $text->delete( 'bar', 'foo' );

If the block was successfully deleted, $result will be true otherwise it will be false., _(*14)

Adding a third boolean parameter will make the block exclusive, i.e. not contain the start and end lines:, _(*15)

$result = $text->delete( 'bar', 'foo', false ); 

replace

The parameters for the replace method are similar to those for delete, except that replacement line(s) are included., _(*16)

$text->replace( 'foo', 'replace', 'bar');

This replaces the block where the first line contains 'bar' and the last line contains 'foo', with the line 'replace'., _(*17)

Again, lines will only be replaced if the block is unique and start line is before the end line. It returns false if the block is invalid., _(*18)

Add false as a fourth parameter to replace the block but exclude the start and end lines:, _(*19)

$text->replace( 'foo', 'replace', 'bar', false );

This method also accepts an array of lines as replacements:, _(*20)

$text->replace( 'foo', ['replace', 'replace', 'replace'], 'bar', false );

find

The find returns the indexes of lines containing a search string. It is used internally by methods such as delete and replace., _(*21)

To find all lines containing 'foo': $result = $text->find( 'foo' ), _(*22)

The result will be an array of indexes, or false if no lines found., _(*23)

This method can also be used to find unique lines by adding a second false parameter:, _(*24)

$result = $text->find( 'foo', false ); 

The result will be an integer, or false if no line found or more than one line is found., _(*25)

prepend

This method adds a single line containing 'foo' to the start of the file: $text->prepend( 'foo' ), _(*26)

Add multiple lines to the start of the file: $text->prepend( ['foo', 'foo', 'foo'] ), _(*27)

append

Add a single line containing 'foo' to the end of the file: $text->append( 'foo' ), _(*28)

Add multiple lines to the end of the file: $text->append( ['foo', 'foo', 'foo'] ), _(*29)

add

This method adds lines before a specified line., _(*30)

To add a line containing 'bar' before the line(s) containing 'foo': $text->add( 'foo', 'bar' ), _(*31)

To add multiple lines before the line(s) containing 'foo': $text->add( 'foo', ['bar', 'bar', 'bar'] ), _(*32)

Extracting lines

The result of extracting lines is a new TextFile object containing the extracted lines., _(*33)

As with other methods, a block of lines to extract is identified by strings in the start line and end lines., _(*34)

This will extract the lines between, and including, the line containing 'bar' and the line containing 'foo':, _(*35)

$result = $text->extract( 'foo', 'bar' );

Adding false as a third parameter will exclude the start and end lines: $result = $text->extract( 'foo', 'bar', false), _(*36)

Leaving out the second parameter will extract all lines from the first to the end of the file, including the first line., _(*37)

$result = $text->extract( 'foo' );

Output

The join method returns the lines as a string with an end of line character between each line., _(*38)

By default, the PHP constant PHP_EOL is used, but it can be set by: $text->setEOL( "\n" ), _(*39)

To echo the contents of the file as a string: echo $text->join(), _(*40)

To save the file $text->save( 'foo.txt' ), _(*41)