PHPackages                             cmatosbc/penelope - 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. cmatosbc/penelope

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

cmatosbc/penelope
=================

Tentative implementation of asynchronous file handling for PHP.

1.0.0(1y ago)33gpl-3.0-or-laterPHPPHP >=8.1

Since Dec 10Pushed 1y ago1 watchersCompare

[ Source](https://github.com/cmatosbc/penelope)[ Packagist](https://packagist.org/packages/cmatosbc/penelope)[ RSS](/packages/cmatosbc-penelope/feed)WikiDiscussions main Synced 1mo ago

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

Penelope 🧵
==========

[](#penelope-)

[![PHP Composer](https://github.com/cmatosbc/penelope/actions/workflows/composer.yml/badge.svg)](https://github.com/cmatosbc/penelope/actions/workflows/composer.yml) [![PHP 8.2 PHPUnit Tests](https://github.com/cmatosbc/penelope/actions/workflows/phpunit.yml/badge.svg)](https://github.com/cmatosbc/penelope/actions/workflows/phpunit.yml)

A high-performance asynchronous file handling library for PHP, leveraging Fibers for non-blocking I/O operations.

🚀 Overview
----------

[](#-overview)

Penelope is designed to handle large file operations efficiently by utilizing PHP's Fiber feature for asynchronous processing. It breaks down file operations into manageable chunks, allowing for better memory management and improved performance, especially for large files.

### Why Penelope?

[](#why-penelope)

- **Memory Efficient**: Process large files without loading them entirely into memory
- **Non-Blocking**: Leverage PHP Fibers for asynchronous operations
- **Flexible**: Support for both synchronous and asynchronous operations
- **Transformable**: Apply custom transformations during read/write operations
- **Progress Tracking**: Monitor write progress in real-time
- **Compression Support**: Built-in support for gzip, bzip2, and deflate compression
- **Error Resilience**: Robust error handling with retry mechanisms and logging

📋 Requirements
--------------

[](#-requirements)

- PHP 8.1 or higher (Fiber support required)
- Composer for dependency management
- PHP Extensions:
    - `zlib` for gzip/deflate compression
    - `bz2` for bzip2 compression (optional)

🛠 Installation
--------------

[](#-installation)

```
composer require cmatosbc/penelope

# For bzip2 support (Ubuntu/Debian)
sudo apt-get install php-bz2
```

📖 Usage
-------

[](#-usage)

### Basic File Reading

[](#basic-file-reading)

```
use Penelope\AsyncFileHandler;

// Create a handler instance
$handler = new AsyncFileHandler('large_file.txt', 'r');

// Synchronous read
$content = $handler->readSync();

// Asynchronous read
$fiber = $handler->readAsync();
$content = '';

$chunk = $fiber->start();
if ($chunk !== null) {
    $content .= $chunk;
}

while ($fiber->isSuspended()) {
    $chunk = $fiber->resume();
    if ($chunk !== null) {
        $content .= $chunk;
    }
}
```

### Compression Support

[](#compression-support)

```
use Penelope\Compression\CompressionHandler;

// Create a compression handler (gzip, bzip2, or deflate)
$compression = new CompressionHandler('gzip', 6); // level 6 compression

// Compress data
$compressed = $compression->compress($data);

// Decompress data
$decompressed = $compression->decompress($compressed);

// Get file extension for compressed files
$extension = $compression->getFileExtension(); // Returns .gz for gzip
```

### Error Handling with Retries

[](#error-handling-with-retries)

```
use Penelope\Error\ErrorHandler;
use Penelope\Error\RetryPolicy;
use Psr\Log\LoggerInterface;

// Create a retry policy with custom settings
$retryPolicy = new RetryPolicy(
    maxAttempts: 3,        // Maximum number of retry attempts
    delayMs: 100,          // Initial delay between retries in milliseconds
    backoffMultiplier: 2.0, // Multiplier for exponential backoff
    maxDelayMs: 5000       // Maximum delay between retries
);

// Create an error handler with custom logger (optional)
$errorHandler = new ErrorHandler($logger, $retryPolicy);

// Execute an operation with retry logic
try {
    $result = $errorHandler->executeWithRetry(
        function() {
            // Your operation here
            return $someResult;
        },
        'Reading file chunk'
    );
} catch (\RuntimeException $e) {
    // Handle final failure after all retries
}
```

### Combining Features

[](#combining-features)

```
use Penelope\AsyncFileHandler;
use Penelope\Compression\CompressionHandler;
use Penelope\Error\ErrorHandler;
use Penelope\Error\RetryPolicy;

// Set up handlers
$compression = new CompressionHandler('gzip');
$retryPolicy = new RetryPolicy(maxAttempts: 3);
$errorHandler = new ErrorHandler(null, $retryPolicy);
$fileHandler = new AsyncFileHandler('large_file.txt', 'r');

// Read and compress file with retry logic
$errorHandler->executeWithRetry(
    function() use ($fileHandler, $compression) {
        $fiber = $fileHandler->readAsync();
        $compressedContent = '';

        // Start reading
        $chunk = $fiber->start();
        if ($chunk !== null) {
            $compressedContent .= $compression->compress($chunk);
        }

        // Continue reading
        while ($fiber->isSuspended()) {
            $chunk = $fiber->resume();
            if ($chunk !== null) {
                $compressedContent .= $compression->compress($chunk);
            }
        }

        // Write compressed content
        file_put_contents('output.gz', $compressedContent);
    },
    'Compressing file'
);
```

🎯 Use Cases
-----------

[](#-use-cases)

### 1. Large File Processing

[](#1-large-file-processing)

Perfect for processing large log files, data exports, or any situation where memory efficiency is crucial:

```
$handler = new AsyncFileHandler('large_log.txt', 'r');
$fiber = $handler->readAsync();

// Process line by line without loading entire file
while ($chunk = $fiber->resume()) {
    // Process chunk
    analyzeLogData($chunk);
}
```

### 2. File Compression and Archiving

[](#2-file-compression-and-archiving)

- Compress large log files for archival
- Create compressed backups of data files
- Stream compressed data to remote storage
- Process and compress multiple files in parallel

### 3. Error-Resilient Operations

[](#3-error-resilient-operations)

- Retry failed network file transfers
- Handle intermittent I/O errors gracefully
- Log detailed error information for debugging
- Implement progressive backoff for rate-limited operations

🔍 Performance
-------------

[](#-performance)

Based on our benchmarks with a 100MB file:

- **Async Read**: ~3.4x faster than synchronous read
- **Async Write**: Comparable to synchronous write
- **Memory Usage**: Consistent across operations
- **Chunk Size**: Default 8KB (configurable)

🧪 Testing
---------

[](#-testing)

```
composer install
./vendor/bin/phpunit --testdox
```

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License
---------

[](#-license)

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. This means:

- You can freely use, modify, and distribute this software
- If you modify and distribute this software, you must:
    - Make your modifications available under GPL-3.0
    - Include the original copyright notice
    - Include the full text of the GPL-3.0 license
    - Make your source code available

⚠️ Important Notes
------------------

[](#️-important-notes)

- Requires PHP 8.1+ for Fiber support
- Performance may vary based on file size and system configuration
- For optimal performance, adjust chunk size based on your use case

🔗 Links
-------

[](#-links)

- [PHP Fibers Documentation](https://www.php.net/manual/en/language.fibers.php)
- [Issue Tracker](https://github.com/your-username/penelope/issues)
- [Contributing Guidelines](CONTRIBUTING.md)

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity48

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

Unknown

Total

1

Last Release

525d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/3d97279f52b70d502ac21c0618e2822a0bae0523a7e69bb3fd33a592f21d5f06?d=identicon)[cmatosbc](/maintainers/cmatosbc)

---

Top Contributors

[![cmatosbc](https://avatars.githubusercontent.com/u/118901076?v=4)](https://github.com/cmatosbc "cmatosbc (16 commits)")

---

Tags

asynchronousasynchronous-phpfilefile-handlingfile-handling-in-phpphp-81php-asynphp-async-file-managerphp-fibphp-fiberphp-filesystem

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cmatosbc-penelope/health.svg)

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

###  Alternatives

[google/cloud

Google Cloud Client Library

1.2k16.2M53](/packages/google-cloud)[magento/community-edition

Magento 2 (Open Source)

12.1k52.1k10](/packages/magento-community-edition)[elgg/elgg

Elgg is an award-winning social networking engine, delivering the building blocks that enable businesses, schools, universities and associations to create their own fully-featured social networks and applications.

1.7k15.7k5](/packages/elgg-elgg)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[puli/repository

A filesystem-like repository for storing arbitrary resources.

44287.6k32](/packages/puli-repository)

PHPackages © 2026

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