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.

1.01(1y ago)24.3k↓50%MITPHPPHP >=8.2CI 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 1mo ago

READMEChangelog (3)Dependencies (5)Versions (5)Used By (0)

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

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

[![Codacy Badge](https://camo.githubusercontent.com/a43ad1567af0143260d5631ca159113758c3effb9ef8dbfddcafb6f3fb758dfc/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f47726164652f3530323838343864323665333466356538383361613234386138383835383131)](https://app.codacy.com/gh/infocyph/Pathwise/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)[![Libraries.io dependency status for GitHub repo](https://camo.githubusercontent.com/3fc0fca9c900d3449dcea24fb16bda874eb17f9cf2e8c49d574df48673d6215f/68747470733a2f2f696d672e736869656c64732e696f2f6c6962726172696573696f2f6769746875622f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/3fc0fca9c900d3449dcea24fb16bda874eb17f9cf2e8c49d574df48673d6215f/68747470733a2f2f696d672e736869656c64732e696f2f6c6962726172696573696f2f6769746875622f696e666f637970682f7061746877697365)[![Packagist Downloads](https://camo.githubusercontent.com/031f9430e90c1beac33d8da7524a0c45b583a35ecfc857a9f38ef01206998c66/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/031f9430e90c1beac33d8da7524a0c45b583a35ecfc857a9f38ef01206998c66/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e666f637970682f7061746877697365)[![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 Support](https://camo.githubusercontent.com/af565fbbaf4034c25f34d7026f7c8d3ff78e10659ce285bb23e365d0823998ee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/af565fbbaf4034c25f34d7026f7c8d3ff78e10659ce285bb23e365d0823998ee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f696e666f637970682f7061746877697365)[![GitHub code size in bytes](https://camo.githubusercontent.com/b187f6637d6d798f278e5b58ebbf78ee44cdaa2d9189392cba6f23727d6e1138/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f696e666f637970682f7061746877697365)](https://camo.githubusercontent.com/b187f6637d6d798f278e5b58ebbf78ee44cdaa2d9189392cba6f23727d6e1138/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f696e666f637970682f7061746877697365)

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.

**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. [Documentation Map](#documentation-map)
6. [Quality Gates](#quality-gates)
7. [FileManager](#filemanager)
    - [SafeFileReader](#safefilereader)
    - [SafeFileWriter](#safefilewriter)
    - [FileOperations](#fileoperations)
    - [FileCompression](#filecompression)
8. [DirectoryManager](#directorymanager)
    - [DirectoryOperations](#directoryoperations)
9. [Utils](#utils)
    - [PathHelper](#pathhelper)
    - [PermissionsHelper](#permissionshelper)
    - [MetadataHelper](#metadatahelper)
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
- `league/flysystem` 3.x
- `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)

- 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.

**Documentation Map**
---------------------

[](#documentation-map)

If you are new to Pathwise, read in this order:

1. [Overview](docs/overview.rst)
2. [Capabilities](docs/capabilities.rst)
3. [Quickstart](docs/quickstart.rst)
4. [Recipes](docs/recipes.rst)

Then use module pages for details:

- [File Manager](docs/file-manager.rst)
- [Directory Manager](docs/directory-manager.rst)
- [Upload Processing](docs/upload-processing.rst)
- [Security](docs/security.rst)
- [Queue](docs/queue.rst)
- [Observability](docs/observability.rst)
- [Indexing](docs/indexing.rst)
- [Retention](docs/retention.rst)
- [Utilities](docs/utilities.rst)

**Quality Gates**
-----------------

[](#quality-gates)

Pathwise includes a cognitive complexity gate powered by `tomasvotruba/cognitive-complexity` on top of PHPStan.

Run it locally:

```
composer test:phpstan
```

Current thresholds (see `phpstan.neon.dist`):

- Class cognitive complexity: `250`
- Function/method cognitive complexity: `9`
- Dependency-tree complexity: `400`

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

---

**Support**
-----------

[](#support)

Having trouble? Create an issue!

**License**
-----------

[](#license)

Pathwise is licensed under the [MIT License](LICENSE).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance68

Regular maintenance activity

Popularity25

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 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 ~2 days

Total

2

Last Release

546d ago

### 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 (17 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

[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k39.8M123](/packages/knplabs-gaufrette)[superbalist/flysystem-google-storage

Flysystem adapter for Google Cloud Storage

26320.6M30](/packages/superbalist-flysystem-google-storage)[illuminate/filesystem

The Illuminate Filesystem package.

15161.6M2.6k](/packages/illuminate-filesystem)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M62](/packages/creocoder-yii2-flysystem)[flowjs/flow-php-server

PHP library for handling chunk uploads. Works with flow.js html5 file uploads.

2451.6M15](/packages/flowjs-flow-php-server)[madnest/madzipper

Easier zip file handling for Laravel applications.

1382.3M6](/packages/madnest-madzipper)

PHPackages © 2026

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