README

File manipulations

Installation
Usage
Maintenance

Installation

composer require alexskrypnyk/file

Usage

This library provides a set of static methods for file and directory operations. All methods are available through the AlexSkrypnyk\File\File class.

use AlexSkrypnyk\File\File;
use AlexSkrypnyk\File\Exception\FileException;

try {
  // Get current working directory
  $cwd = File::cwd();

  // Copy a directory recursively
  File::copy('/path/to/source', '/path/to/destination');

  // Check if a file contains a string
  if (File::contains('/path/to/file.txt', 'search term')) {
    // Do something
  }
} catch (FileException $exception) {
  // Handle any file operation errors
  echo $exception->getMessage();
}

Available Functions

Function	Description
`absolute()`	Get absolute path for provided absolute or relative file.
`compare()`	Compare files between source and destination directories.
`contains()`	Check if file contains a specific string or matches a pattern.
`containsInDir()`	Find all files in directory containing a specific string.
`copy()`	Copy file or directory.
`copyIfExists()`	Copy file or directory if it exists.
`cwd()`	Get current working directory with absolute path.
`diff()`	Create diff files between baseline and destination directories. See Diff Operations below.
`dir()`	Get absolute path for existing directory.
`dirIsEmpty()`	Check if directory is empty.
`dump()`	Write content to a file.
`exists()`	Check if file or directory exists.
`findMatchingPath()`	Find first path that matches a needle among provided paths.
`mkdir()`	Creates a directory if it doesn't exist.
`patch()`	Apply patch files to a baseline and produce a destination.
`read()`	Read file contents.
`realpath()`	Replacement for PHP's `realpath` resolves non-existing paths.
`remove()`	Remove file or directory.
`removeLine()`	Remove lines containing a specific string from a file.
`removeToken()`	Remove tokens and optionally content between tokens from a file.
`removeTokenInDir()`	Remove tokens and optionally content between tokens from all files in a directory.
`renameInDir()`	Rename files in directory by replacing part of the filename.
`replaceContent()`	Replace content in a file.
`replaceContentInDir()`	Replace content in all files in a directory.
`rmdir()`	Remove directory recursively.
`rmdirEmpty()`	Remove directory recursively if empty.
`scandirRecursive()`	Recursively scan directory for files.
`sync()`	Synchronize files from source to destination directory.
`tmpdir()`	Create temporary directory.

Diff Operations

The diff(), patch(), and compare() functions provide powerful tools for working with file differences between directories:

use AlexSkrypnyk\File\File;
use AlexSkrypnyk\File\Exception\PatchException;

// Generate diff files between baseline and destination directories
File::diff('/path/to/baseline', '/path/to/destination', '/path/to/diff');

// Compare directories to determine if they're equal
$result = File::compare('/path/to/source', '/path/to/destination');

// Apply patches to transform a baseline directory
try {
  File::patch('/path/to/baseline', '/path/to/diff', '/path/to/patched');
} catch (PatchException $exception) {
  echo $exception->getMessage(); // Returns a detailed error message.

  // Additional contextual information
  $path = $exception->getFilePath();    // Gets the affected file path.
  $line_number = $exception->getLineNumber(); // Gets the line number where the error occurred.
  $line_content = $exception->getLineContent(); // Gets the content of the problematic line.
}

The diff functionality allows you to:

Generate differences between two directory structures
Store those differences as patch files
Apply those patches to recreate directory structures elsewhere

The PatchException provides detailed error messages with contextual information when patch operations fail, making debugging easier.

Ignoring Files and Content Changes

You can create a .ignorecontent file in your directories to specify patterns for files or content that should be ignored during comparison. This is useful for timestamps, randomly generated values, or files that shouldn't be compared.

The syntax for .ignorecontent file is similar to .gitignore with additional content ignoring capabilities:

# Comments start with #
file.txt        # Ignore this specific file
logs/           # Ignore this directory and all subdirectories
temp/*          # Ignore all files in directory, but not subdirectories
^config.json    # Ignore content changes in this file, but check file exists
^data/          # Ignore content changes in all files in dir and subdirs
^cache/*        # Ignore content changes in all files in dir, but not subdirs
!important.txt  # Do not ignore this file (exception)
!^settings.php  # Do not ignore content changes in this file

Prefix meanings:

No prefix: Ignore file/directory completely
^: Ignore content changes but verify file/directory exists
!: Exception - do not ignore this file/directory
!^: Exception - do not ignore content changes in this file/directory

When parsing these rules, the library may throw a RulesException if there are issues:

use AlexSkrypnyk\File\File;
use AlexSkrypnyk\File\Exception\RulesException;

try {
  // Operations using .ignorecontent rules
  File::compare('/path/to/source', '/path/to/destination');
} catch (RulesException $exception) {
  // Handle rules parsing errors
  echo $exception->getMessage();
}

Assertion Traits

The library includes PHPUnit traits for testing files and directories:

Directory Assertions Trait

Assertion Method	Description
`assertDirectoryContainsString()`	Assert that a directory contains files with a specific string.
`assertDirectoryNotContainsString()`	Assert that a directory does not contain files with a specific string.
`assertDirectoryContainsWord()`	Assert that a directory contains files with a specific word (bounded by word boundaries).
`assertDirectoryNotContainsWord()`	Assert that a directory does not contain files with a specific word.
`assertDirectoryEqualsDirectory()`	Assert that two directories have identical structure and content.
`assertDirectoryEqualsPatchedBaseline()`	Assert that a directory is equal to the patched baseline (baseline + diff).

Usage example:

use PHPUnit\Framework\TestCase;
use AlexSkrypnyk\File\Tests\Traits\DirectoryAssertionsTrait;

class MyTest extends TestCase {
  use DirectoryAssertionsTrait;

  public function testDirectories(): void {
    // Assert directory contains "example" string in at least one file
    $this->assertDirectoryContainsString('example', '/path/to/directory');

    // Assert two directories are identical
    $this->assertDirectoryEqualsDirectory('/path/to/dir1', '/path/to/dir2');
  }
}

File Assertions Trait

Assertion Method	Description
`assertFileContainsString()`	Assert that a file contains a specific string.
`assertFileNotContainsString()`	Assert that a file does not contain a specific string.
`assertFileContainsWord()`	Assert that a file contains a specific word (bounded by word boundaries).
`assertFileNotContainsWord()`	Assert that a file does not contain a specific word.
`assertFileEqualsFile()`	Assert that a file equals another file in contents.
`assertFileNotEqualsFile()`	Assert that a file does not equal another file in contents.

Usage example:

use PHPUnit\Framework\TestCase;
use AlexSkrypnyk\File\Tests\Traits\FileAssertionsTrait;

class MyTest extends TestCase {
  use FileAssertionsTrait;

  public function testFiles(): void {
    // Assert file contains "example" string
    $this->assertFileContainsString('example', '/path/to/file.txt');

    // Assert file contains "test" as a complete word
    $this->assertFileContainsWord('test', '/path/to/file.txt');

    // Assert file does not contain a partial word
    $this->assertFileNotContainsWord('exampl', '/path/to/file.txt');

    // Assert two files have identical content
    $this->assertFileEqualsFile('/path/to/expected.txt', '/path/to/actual.txt');

    // Assert two files have different content
    $this->assertFileNotEqualsFile('/path/to/expected.txt', '/path/to/actual.txt');
  }
}

Maintenance

composer install
composer lint
composer test

This repository was created using the Scaffold project template

alexskrypnyk / file

Maintainers

Details