alexskrypnyk / file
Provides file manipulations functionality.
Fund package maintenance!
alexskrypnyk
Patreon
Requires
- php: >=8.2
- symfony/filesystem: ^7.2
Requires (Dev)
- dev-main
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.0
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.2
- 0.1.1
- 0.1.0
- dev-renovate/alexskrypnyk-phpunit-helpers-0.x
- dev-feature/fix-rename
- dev-feature/fix-delete-empty-dir-links
- dev-feature/fix-delete-empty-dir
- dev-feature/fix-dir-assertion
- dev-feature/exceptions
- dev-feature/update-test-helpers
- dev-feature/file-assertions
This package is auto-updated.
Last update: 2025-04-18 06:35:09 UTC
README
File manipulations
Table of Contents
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