Pathwise is a robust PHP library designed as Flysystem + more for streamlined file and directory management. It combines Flysystem-backed storage operations with higher-level workflows like safe reading/writing, metadata extraction, compression, upload pipelines, policy enforcement, and observability.
- Introduction
- Prerequisites
- Installation
- Features Overview
- Documentation Map
- Quality Gates
- FileManager
- DirectoryManager
- Utils
- Handy Functions
- Support
- License
- Language: PHP 8.4/+
Pathwise is available via Composer:
composer require infocyph/pathwiseRequirements:
- PHP 8.4 or higher
league/flysystem3.xext-fileinfo- Optional Extensions:
ext-zip: Required for compression features.ext-pcntl: Required for long-running watch loops.ext-posix: Required for permission handling.ext-xmlreaderandext-simplexml: Required for XML parsing.
- Flysystem-first filesystem operations across core modules.
- Mount support with scheme paths (
name://path) and default filesystem support for relative paths. - Advanced file APIs: checksum verification, visibility controls, URL passthrough (
publicUrl,temporaryUrl). - Directory automation: sync with diff report, recursive copy/move/delete, mounted-path ZIP/unzip bridging.
- Upload pipelines: chunked/resumable uploads, validation profiles (image/video/document), malware-scan hook.
- Compression workflows: include/exclude glob patterns, ignore files, progress callbacks, hooks, optional native acceleration.
- Operational tooling:
AuditTrail,FileJobQueue,FileWatcher,RetentionManager, and policy engine support.
If you are new to Pathwise, read in this order:
Then use module pages for details:
- File Manager
- Directory Manager
- Upload Processing
- Security
- Queue
- Observability
- Indexing
- Retention
- Utilities
Pathwise includes a cognitive complexity gate powered by tomasvotruba/cognitive-complexity on top of PHPStan.
Run it locally:
composer test:phpstanCurrent thresholds (see phpstan.neon.dist):
- Class cognitive complexity:
250 - Function/method cognitive complexity:
9 - Dependency-tree complexity:
400
The FileManager module provides classes for handling files, including reading, writing, compressing, and general file operations.
A memory-safe file reader supporting various reading modes (line-by-line, binary chunks, JSON, CSV, XML, etc.) and iterator interfaces.
- Supports multiple reading modes.
- Provides locking to prevent concurrent access issues.
- Implements
Countable,Iterator, andSeekableIterator.
use Infocyph\Pathwise\FileManager\SafeFileReader;
$reader = new SafeFileReader('/path/to/file.txt');
// Line-by-line iteration
foreach ($reader->line() as $line) {
echo $line;
}
// JSON decoding with error handling
foreach ($reader->json() as $data) {
print_r($data);
}A memory-safe file writer with support for various writing modes, including CSV, JSON, binary, and more.
- Supports multiple writing modes.
- Ensures file locking and robust error handling.
- Tracks write operations and supports flush and truncate methods.
use Infocyph\Pathwise\FileManager\SafeFileWriter;
$writer = new SafeFileWriter('/path/to/file.txt');
// Writing lines
$writer->line('Hello, World!');
// Writing JSON data
$writer->json(['key' => 'value']);General-purpose file handling class for creating, deleting, copying, renaming, and manipulating files.
- File creation and deletion.
- Append and update content.
- Rename, copy, and metadata retrieval.
use Infocyph\Pathwise\FileManager\FileOperations;
$fileOps = new FileOperations('/path/to/file.txt');
// Check existence
if ($fileOps->exists()) {
echo 'File exists';
}
// Read content
echo $fileOps->read();Provides utilities for compressing and decompressing files using the ZIP format with optional password protection and encryption.
- Compress files/directories.
- Decompress ZIP archives.
- Support for AES encryption and password-protected ZIPs.
use Infocyph\Pathwise\FileManager\FileCompression;
$compression = new FileCompression('/path/to/archive.zip');
// Compress a directory
$compression->compress('/path/to/directory');
// Decompress
$compression->decompress('/path/to/extract/');The DirectoryManager module offers tools for handling directory creation, deletion, and traversal.
Provides comprehensive tools for managing directories, including creation, deletion, copying, and listing contents.
- Create, delete, and copy directories.
- Retrieve directory size, depth, and contents.
- Supports recursive operations and filtering.
use Infocyph\Pathwise\DirectoryManager\DirectoryOperations;
$dirOps = new DirectoryOperations('/path/to/directory');
// Create a directory
$dirOps->create();
// List contents
$contents = $dirOps->listContents(detailed: true);
print_r($contents);Utility classes for managing paths, permissions, and metadata.
Provides utilities for working with file paths, including joining, normalizing, and converting between relative and absolute paths.
- Path joining and normalization.
- Convert between relative and absolute paths.
- Retrieve and manipulate file extensions.
use Infocyph\Pathwise\Utils\PathHelper;
$absolutePath = PathHelper::toAbsolutePath('relative/path');
echo $absolutePath;
$joinedPath = PathHelper::join('/var', 'www', 'html');
echo $joinedPath;Handles file and directory permissions, ownership, and access control.
- Retrieve and set permissions.
- Check read, write, and execute access.
- Retrieve and set ownership details.
use Infocyph\Pathwise\Utils\PermissionsHelper;
// Get human-readable permissions
echo PermissionsHelper::getHumanReadablePermissions('/path/to/file');
// Check if writable
if (PermissionsHelper::canWrite('/path/to/file')) {
echo 'File is writable';
}Extracts metadata for files and directories, such as size, timestamps, MIME type, and more.
- Retrieve file size and type.
- Compute checksums and timestamps.
- Get ownership and visibility details.
use Infocyph\Pathwise\Utils\MetadataHelper;
// Get file size
$size = MetadataHelper::getFileSize('/path/to/file');
echo "File size: $size bytes";
// Retrieve metadata
$metadata = MetadataHelper::getAllMetadata('/path/to/file');
print_r($metadata);Pathwise provides standalone utility functions to simplify common file and directory operations.
Formats a file size in bytes into a human-readable format (e.g., 1.23 KB, 4.56 GB).
Usage Example:
$size = getHumanReadableFileSize(123456789);
echo $size; // Output: "117.74 MB"Checks whether the given directory contains any files or subdirectories.
Usage Example:
$isEmpty = isDirectoryEmpty('/path/to/directory');
echo $isEmpty ? 'Empty' : 'Not Empty';Deletes a directory and all its contents (files and subdirectories).
Usage Example:
$success = deleteDirectory('/path/to/directory');
echo $success ? 'Deleted successfully' : 'Failed to delete';Calculates the total size of a directory, including all its files and subdirectories.
Usage Example:
$size = getDirectorySize('/path/to/directory');
echo "Directory size: " . getHumanReadableFileSize($size);Creates a directory (including parent directories) with specified permissions.
Usage Example:
$success = createDirectory('/path/to/new/directory');
echo $success ? 'Directory created' : 'Failed to create directory';Lists all files in a directory, excluding subdirectories.
Usage Example:
$files = listFiles('/path/to/directory');
print_r($files);Copies a directory and all its contents to a new location.
Usage Example:
$success = copyDirectory('/source/directory', '/destination/directory');
echo $success ? 'Copied successfully' : 'Failed to copy';Having trouble? Create an issue!
Pathwise is licensed under the MIT License.