PHPackages                             infocyph/pathwise - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. infocyph/pathwise

ActiveLibrary[File & Storage](/categories/file-storage)

infocyph/pathwise
=================

File management made simple.

2.5.1(1mo ago)25.5k↑38.4%2MITPHPPHP >=8.4CI passing

Since Nov 16Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/infocyph/Pathwise)[ Packagist](https://packagist.org/packages/infocyph/pathwise)[ RSS](/packages/infocyph-pathwise/feed)WikiDiscussions main Synced yesterday

READMEChangelog (9)Dependencies (7)Versions (14)Used By (2)

Pathwise: File Management Made Simple
=====================================

[](#pathwise-file-management-made-simple)

[![Security & Standards](https://github.com/infocyph/Pathwise/actions/workflows/security-standards.yml/badge.svg)](https://github.com/infocyph/Pathwise/actions/workflows/security-standards.yml)[![Documentation](https://camo.githubusercontent.com/e5d5eb023ca3ba3451feae8506631bed7c0f4a3ebcec39188a2d8f37a95b152d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f63756d656e746174696f6e2d50617468776973652d626c75653f6c6f676f3d72656164746865646f6373266c6f676f436f6c6f723d7768697465)](https://docs.infocyph.com/projects/pathwise/)[![Packagist Downloads](https://camo.githubusercontent.com/ae4ad01f9bc882f8b5e5fbd0869783b6bb8bf387fef0356b95ce45dc829e0a2b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e666f637970682f70617468776973653f636f6c6f723d677265656e266c696e6b3d68747470732533412532462532467061636b61676973742e6f72672532467061636b61676573253246696e666f637970682532467061746877697365)](https://camo.githubusercontent.com/ae4ad01f9bc882f8b5e5fbd0869783b6bb8bf387fef0356b95ce45dc829e0a2b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e666f637970682f70617468776973653f636f6c6f723d677265656e266c696e6b3d68747470732533412532462532467061636b61676973742e6f72672532467061636b61676573253246696e666f637970682532467061746877697365)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](https://opensource.org/licenses/MIT)[![Packagist Version](https://camo.githubusercontent.com/ad153a635c57dd55ef1b1f9ef1c3929deb18ac7b3de1fd21148723f2388b7be9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/ad153a635c57dd55ef1b1f9ef1c3929deb18ac7b3de1fd21148723f2388b7be9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696e666f637970682f7061746877697365)[![Packagist PHP Version](https://camo.githubusercontent.com/3900771c5efc90a689fdfa298252386c88944a736a14a756fb7d09b7869df79e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f696e666f637970682f70617468776973652f706870)](https://camo.githubusercontent.com/3900771c5efc90a689fdfa298252386c88944a736a14a756fb7d09b7869df79e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f696e666f637970682f70617468776973652f706870)[![GitHub Code Size](https://camo.githubusercontent.com/b187f6637d6d798f278e5b58ebbf78ee44cdaa2d9189392cba6f23727d6e1138/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/b187f6637d6d798f278e5b58ebbf78ee44cdaa2d9189392cba6f23727d6e1138/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f696e666f637970682f7061746877697365)

Pathwise is a robust PHP library designed as streamlined file and directory management. It combines storage operations with higher-level workflows like safe reading/writing, metadata extraction, compression, upload pipelines, policy enforcement and observability.

**Table of Contents**
---------------------

[](#table-of-contents)

1. [Introduction](#pathwise-file-management-made-simple)
2. [Prerequisites](#prerequisites)
3. [Installation](#installation)
4. [Features Overview](#features-overview)
5. [Quality Gates](#quality-gates)
6. [FileManager](#filemanager)
    - [SafeFileReader](#safefilereader)
    - [SafeFileWriter](#safefilewriter)
    - [FileOperations](#fileoperations)
    - [FileCompression](#filecompression)
7. [DirectoryManager](#directorymanager)
    - [DirectoryOperations](#directoryoperations)
8. [Utils](#utils)
    - [PathHelper](#pathhelper)
    - [PermissionsHelper](#permissionshelper)
    - [MetadataHelper](#metadatahelper)
9. [Storage Adapter Setup](#storage-adapter-setup)
10. [Handy Functions](#handy-functions)

- [File and Directory Utilities](#file-and-directory-utilities)

11. [Support](#support)
12. [License](#license)

**Prerequisites**
-----------------

[](#prerequisites)

- Language: PHP 8.4/+

**Installation**
----------------

[](#installation)

Pathwise is available via Composer:

```
composer require infocyph/pathwise
```

Requirements:

- PHP 8.4 or higher
- `ext-fileinfo`
- Optional Extensions:
    - `ext-zip`: Required for compression features.
    - `ext-pcntl`: Required for long-running watch loops.
    - `ext-posix`: Required for permission handling.
    - `ext-xmlreader` and `ext-simplexml`: Required for XML parsing.

---

**Features Overview**
---------------------

[](#features-overview)

- Filesystem operations across core modules.
- Mount support with scheme paths (`name://path`) and default filesystem support for relative paths.
- Config-driven storage bootstrap via `StorageFactory` for local/custom/adapter-based filesystems.
- Unified entry facade via `Infocyph\Pathwise\PathwiseFacade` for file/dir/processors/storage/tooling.
- 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/download pipelines: chunked/resumable uploads, validation profiles (image/video/document), extension allow/deny controls, strict MIME/signature checks, upload-id safety validation, malware-scan hook, secure download metadata + range handling.
- Compression workflows: include/exclude glob patterns, ignore files, progress callbacks, hooks, optional native acceleration.
- Operational tooling: `AuditTrail`, `FileJobQueue`, `FileWatcher`, `RetentionManager` and policy engine support.

**Storage Adapter Setup**
-------------------------

[](#storage-adapter-setup)

Pathwise supports any Flysystem adapter. You can mount storages through `StorageFactory` and use them with all modules (`UploadProcessor`, `DownloadProcessor`, `FileOperations`, etc.).

`StorageFactory` supports:

- `['driver' => 'local', 'root' => '/path']`
- `['driver' => 'aws-s3', 'adapter' => $adapter]`
- `['driver' => 'aws-s3', 'constructor' => [...]]`
- `['filesystem' => $filesystemOperator]`
- custom drivers via `StorageFactory::registerDriver()`

Official adapter driver keys covered:

- `local`, `ftp`, `inmemory` (`in-memory`)
- `read-only`, `path-prefixing`
- `aws-s3` (`s3`), `async-aws-s3`
- `azure-blob-storage`, `google-cloud-storage`, `mongodb-gridfs`
- `sftp-v2`, `sftp-v3`, `webdav`, `ziparchive`

### **Local Driver**

[](#local-driver)

```
use Infocyph\Pathwise\Storage\StorageFactory;
use Infocyph\Pathwise\Utils\FlysystemHelper;

StorageFactory::mount('assets', [
    'driver' => 'local',
    'root' => '/srv/storage/assets',
]);

FlysystemHelper::write('assets://reports/a.txt', 'hello');
```

### **Any Adapter (Example: S3)**

[](#any-adapter-example-s3)

```
use Aws\S3\S3Client;
use Infocyph\Pathwise\Storage\StorageFactory;
use League\Flysystem\AwsS3V3\AwsS3V3Adapter;

$client = new S3Client([
    'version' => 'latest',
    'region' => 'us-east-1',
    'credentials' => [
        'key' => getenv('AWS_ACCESS_KEY_ID'),
        'secret' => getenv('AWS_SECRET_ACCESS_KEY'),
    ],
]);

$adapter = new AwsS3V3Adapter($client, 'my-bucket', 'app-prefix');

StorageFactory::mount('s3', ['adapter' => $adapter]);
// Use s3://... paths in processors and managers.
```

### **Custom Driver Registration**

[](#custom-driver-registration)

```
use Infocyph\Pathwise\Storage\StorageFactory;
use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;

StorageFactory::registerDriver('tenant-local', function (array $config): Filesystem {
    $tenant = (string) ($config['tenant'] ?? 'default');
    return new Filesystem(new LocalFilesystemAdapter('/srv/tenants/' . $tenant));
});

StorageFactory::mount('tenant', [
    'driver' => 'tenant-local',
    'tenant' => 'acme',
]);
```

**Unified Pathwise Facade**
---------------------------

[](#unified-pathwise-facade)

Use a single entry point when you want fewer direct class imports.

```
use Infocyph\Pathwise\PathwiseFacade;

$entry = PathwiseFacade::at('/tmp/example.txt');
$entry->file()->create('hello')->append("\nworld");

$upload = PathwiseFacade::upload();
$download = PathwiseFacade::download();

PathwiseFacade::mountStorage('assets', ['driver' => 'local', 'root' => '/srv/assets']);
```

**FileManager**
---------------

[](#filemanager)

The `FileManager` module provides classes for handling files, including reading, writing, compressing and general file operations.

### **SafeFileReader**

[](#safefilereader)

A memory-safe file reader supporting various reading modes (line-by-line, binary chunks, JSON, CSV, XML, etc.) and iterator interfaces.

#### **Key Features**

[](#key-features)

- Supports multiple reading modes.
- Provides locking to prevent concurrent access issues.
- Implements `Countable`, `Iterator` and `SeekableIterator`.

#### **Usage Example**

[](#usage-example)

```
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);
}
```

### **SafeFileWriter**

[](#safefilewriter)

A memory-safe file writer with support for various writing modes, including CSV, JSON, binary and more.

#### **Key Features**

[](#key-features-1)

- Supports multiple writing modes.
- Ensures file locking and robust error handling.
- Tracks write operations and supports flush and truncate methods.

#### **Usage Example**

[](#usage-example-1)

```
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']);
```

### **FileOperations**

[](#fileoperations)

General-purpose file handling class for creating, deleting, copying, renaming and manipulating files.

#### **Key Features**

[](#key-features-2)

- File creation and deletion.
- Append and update content.
- Rename, copy and metadata retrieval.

#### **Usage Example**

[](#usage-example-2)

```
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();
```

### **FileCompression**

[](#filecompression)

Provides utilities for compressing and decompressing files using the ZIP format with optional password protection and encryption.

#### **Key Features**

[](#key-features-3)

- Compress files/directories.
- Decompress ZIP archives.
- Support for AES encryption and password-protected ZIPs.

#### **Usage Example**

[](#usage-example-3)

```
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/');
```

**DirectoryManager**
--------------------

[](#directorymanager)

The `DirectoryManager` module offers tools for handling directory creation, deletion and traversal.

### **DirectoryOperations**

[](#directoryoperations)

Provides comprehensive tools for managing directories, including creation, deletion, copying and listing contents.

#### **Key Features**

[](#key-features-4)

- Create, delete and copy directories.
- Retrieve directory size, depth and contents.
- Supports recursive operations and filtering.

#### **Usage Example**

[](#usage-example-4)

```
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);
```

**Utils**
---------

[](#utils)

Utility classes for managing paths, permissions and metadata.

### **PathHelper**

[](#pathhelper)

Provides utilities for working with file paths, including joining, normalizing and converting between relative and absolute paths.

#### **Key Features**

[](#key-features-5)

- Path joining and normalization.
- Convert between relative and absolute paths.
- Retrieve and manipulate file extensions.

#### **Usage Example**

[](#usage-example-5)

```
use Infocyph\Pathwise\Utils\PathHelper;

$absolutePath = PathHelper::toAbsolutePath('relative/path');
echo $absolutePath;

$joinedPath = PathHelper::join('/var', 'www', 'html');
echo $joinedPath;
```

### **PermissionsHelper**

[](#permissionshelper)

Handles file and directory permissions, ownership and access control.

#### **Key Features**

[](#key-features-6)

- Retrieve and set permissions.
- Check read, write and execute access.
- Retrieve and set ownership details.

#### **Usage Example**

[](#usage-example-6)

```
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';
}
```

### **MetadataHelper**

[](#metadatahelper)

Extracts metadata for files and directories, such as size, timestamps, MIME type and more.

#### **Key Features**

[](#key-features-7)

- Retrieve file size and type.
- Compute checksums and timestamps.
- Get ownership and visibility details.

#### **Usage Example**

[](#usage-example-7)

```
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);
```

**Handy Functions**
-------------------

[](#handy-functions)

### **File and Directory Utilities**

[](#file-and-directory-utilities)

Pathwise provides standalone utility functions to simplify common file and directory operations.

#### **1. Get Human-Readable File Size**

[](#1-get-human-readable-file-size)

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"
```

#### **2. Check if a Directory is Empty**

[](#2-check-if-a-directory-is-empty)

Checks whether the given directory contains any files or subdirectories.

**Usage Example:**

```
$isEmpty = isDirectoryEmpty('/path/to/directory');
echo $isEmpty ? 'Empty' : 'Not Empty';
```

#### **3. Delete a Directory Recursively**

[](#3-delete-a-directory-recursively)

Deletes a directory and all its contents (files and subdirectories).

**Usage Example:**

```
$success = deleteDirectory('/path/to/directory');
echo $success ? 'Deleted successfully' : 'Failed to delete';
```

#### **4. Get Directory Size**

[](#4-get-directory-size)

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);
```

#### **5. Create a Directory**

[](#5-create-a-directory)

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';
```

#### **6. List Files in a Directory**

[](#6-list-files-in-a-directory)

Lists all files in a directory, excluding subdirectories.

**Usage Example:**

```
$files = listFiles('/path/to/directory');
print_r($files);
```

#### **7. Copy a Directory Recursively**

[](#7-copy-a-directory-recursively)

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';
```

Security
--------

[](#security)

Protected by [PHPForge](https://github.com/infocyph/PHPForge) — an automated quality and security gate for PHP projects.

---

 **Made with ❤️ for the PHP community**
 [MIT Licensed](LICENSE)
 [Documentation](https://docs.infocyph.com/projects/Pathwise) • [Security](SECURITY.md) • [Code of Conduct](CODE_OF_CONDUCT.md) • [Contributing](CONTRIBUTING.md) • [Report | Request | Suggest](https://github.com/infocyph/Pathwise/issues)

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance90

Actively maintained with recent releases

Popularity26

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~61 days

Recently: every ~8 days

Total

10

Last Release

46d ago

Major Versions

1.01 → 2.02026-04-04

PHP version history (2 changes)1.0PHP >=8.2

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/33b750b84ab22f2038ef9b90ee48f2fcdaab6b5698e9f956a89a152466200b63?d=identicon)[abmmhasan](/maintainers/abmmhasan)

---

Top Contributors

[![abmmhasan](https://avatars.githubusercontent.com/u/7711128?v=4)](https://github.com/abmmhasan "abmmhasan (55 commits)")

###  Code Quality

TestsPest

Static AnalysisRector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/infocyph-pathwise/health.svg)

```
[![Health](https://phpackages.com/badges/infocyph-pathwise/health.svg)](https://phpackages.com/packages/infocyph-pathwise)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.7k285.7M1.0k](/packages/league-flysystem-aws-s3-v3)[unisharp/laravel-filemanager

A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE

2.2k3.5M85](/packages/unisharp-laravel-filemanager)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[league/flysystem-bundle

Symfony bundle integrating Flysystem into Symfony applications

40432.5M136](/packages/league-flysystem-bundle)[alexusmai/laravel-file-manager

File manager for Laravel

1.2k803.2k9](/packages/alexusmai-laravel-file-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)