PHPackages                             esplora/decompresso - 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. esplora/decompresso

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

esplora/decompresso
===================

PHP library for unlock contents from various files with ease.

1.1.0(10mo ago)1262[2 PRs](https://github.com/bunnivo/lumos/pulls)MITPHPPHP ^8.2CI passing

Since Aug 20Pushed 4mo ago2 watchersCompare

[ Source](https://github.com/bunnivo/lumos)[ Packagist](https://packagist.org/packages/esplora/decompresso)[ RSS](/packages/esplora-decompresso/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (7)Versions (15)Used By (0)

[![Lumos](.github/logo.svg?sanitize=true)](.github/logo.svg?sanitize=true) Lumos
================================================================================

[](#-lumos)

[![Tests](https://github.com/esplora/decompresso/actions/workflows/phpunit.yml/badge.svg)](https://github.com/esplora/decompresso/actions/workflows/phpunit.yml)[![Quality Assurance](https://github.com/esplora/lumos/actions/workflows/quality.yml/badge.svg)](https://github.com/esplora/lumos/actions/workflows/quality.yml)[![Coding Guidelines](https://github.com/esplora/lumos/actions/workflows/php-cs-fixer.yml/badge.svg)](https://github.com/esplora/lumos/actions/workflows/php-cs-fixer.yml)

Lumos is a library that provides a interface for removing passwords from protected documents and archives (extracting content), making these tasks simple and accessible.

###### What can I use this for?

[](#what-can-i-use-this-for)

- Integrating with DLP platforms for protected file processing, ensuring compliance with corporate policies.
- Unlock password-protected documents and archives for data extraction using tools like [Apache Tika](https://tika.apache.org/).
- Utilize online services for removing passwords or recovering them through methods like brute force.

External Dependencies
---------------------

[](#external-dependencies)

Lumos uses the following third-party tools for operations. Each adapter is provided out of the box in the `Esplora\Lumos\Adapters\*` namespace:

**File Type****Tool****Adapter Class**PDF[qpdf](https://github.com/qpdf/qpdf)QpdfAdapterMicrosoft Office[msoffcrypto-tool](https://github.com/nolze/msoffcrypto-tool)MSOfficeCryptoToolAdapterArchive (ZIP, 7z)[7-zip](https://www.7-zip.org/)SevenZipAdapterGnuPG (.gpg)[gpg](https://gnupg.org/)GpgAdapterEmail Message Format (.eml)[cosmira/envelope](https://github.com/cosmira/envelope)EnvelopeAdapterInstallation
------------

[](#installation)

Install the library using Composer:

```
composer require esplora/lumos
```

Basic Usage
-----------

[](#basic-usage)

To get started, create an instance of the `Extractor` class and add the necessary adapters for file formats. The example below demonstrates using `SevenZipAdapter` for archive, but you can add your own adapters:

```
use Esplora\Lumos\Extractor;
use Esplora\Lumos\Adapters\SevenZipAdapter;

$lumos = Extractor::make([
    new SevenZipAdapter(),
])
    ->extract('/path/to/your/archive.zip');

$lumos->isSuccessful(); // true
$lumos->attempts(); // 1
```

Note

When multiple adapters are suitable for a given file, the first adapter in the list will be selected.

Handling Password-Protected Files
---------------------------------

[](#handling-password-protected-files)

To work with password-protected documents, add a password provider. The example below uses `ArrayPasswordProvider`, which accepts an array of passwords.

```
use Esplora\Lumos\Extractor;
use Esplora\Lumos\Adapters\QpdfAdapter;
use Esplora\Lumos\Adapters\SevenZipAdapter;
use Esplora\Lumos\Adapters\MSOfficeCryptoToolAdapter;
use Esplora\Lumos\Providers\ArrayPasswordProvider;

$passwords = new ArrayPasswordProvider([
    'qwerty',
    'xxx123',
]);

Extractor::make()
    ->withAdapters([
        new QpdfAdapter(),
        new SevenZipAdapter(),
        new MSOfficeCryptoToolAdapter(),
    ])
    ->withPasswords($passwords)
    ->extract('/path/to/your/archive.zip', '/path/to/save/to')
    ->isSuccessful(); // false
```

If needed, you can create your own password provider by implementing the `PasswordProviderInterface`.

Tip

If you don’t have a password database but want to try all possible combinations, you can use [SecLists](https://github.com/danielmiessler/SecLists/tree/master/Passwords) as a source of popular passwords for brute-forcing.

Creating Custom Adapters
------------------------

[](#creating-custom-adapters)

Lumos allows you to easily add support for new file types by creating custom adapters. To do so, implement a class that conforms to the `Esplora\Lumos\Contracts\AdapterInterface`.

Example of a custom adapter implementation:

```
namespace Esplora\Lumos\Adapters;

use Esplora\Lumos\Contracts\AdapterInterface;
use Esplora\Lumos\Contracts\PasswordProviderInterface;
use Esplora\Lumos\Results\SummaryInterface;

class CustomAdapter implements AdapterInterface
{
    /**
     * Checks if the adapter supports the given file.
     */
    public function canSupport(string $filePath): bool
    {
        return str_ends_with($filePath, '.custom');
    }

    /**
     * Checks if the environment is properly configured.
     */
    public function isSupportedEnvironment(): bool
    {
        return true; // Check external dependencies here
    }

    /**
     * Extracts the content to the specified directory.
     */
    public function extract(string $filePath, string $destination, PasswordProviderInterface $passwords): SummaryInterface
    {
        // Implement extraction logic here
    }
}
```

The library provides common tools to check if a specific file is supported using built-in traits:

To check based on the file's MIME type, use the trait `SupportsMimeTypes`:

```
use Esplora\Lumos\Concerns\SupportsMimeTypes;

class CustomAdapter implements AdapterInterface
{
    use SupportsMimeTypes;

    /**
     * Returns a list of supported MIME types.
     *
     * @return array An array of supported MIME types.
     */
    protected function supportedMimeTypes(): array
    {
        return [
            'application/pdf', // Support for PDF files
            'image/jpeg',      // Support for JPEG images
        ];
    }

    // ...
}
```

To check based on file extensions, use the trait `SupportsFileExtensions`:

```
use Esplora\Lumos\Concerns\SupportsFileExtensions;

class CustomAdapter implements AdapterInterface
{
    use SupportsFileExtensions;

    /**
     * Returns a list of allowed file extensions.
     *
     * @return array An array of allowed extensions.
     */
    protected function allowedExtensions(): array
    {
        return [
            'txt',  // Support for text files
            'zip',  // Support for ZIP archives
        ];
    }

    // ...
}
```

Testing
-------

[](#testing)

Testing an application that depends on other services can be challenging, but this should not prevent you from contributing to the project.

For adapters that depend on executable files, you can pass the path via the constructor:

```
use Esplora\Lumos\Adapters\SevenZipAdapter;

new SevenZipAdapter('/usr/bin/7z'),
```

For convenience, we also support using environment variables from a `.env` file to store paths to dependency executables in one place. To do this, create a `.env` file at the root of your project and add the environment variables as shown in the `.env.example`.

Warning

Environment variables from the `.env` file will be loaded only for local testing and are added solely for the convenience of developing this package.

Troubleshooting
---------------

[](#troubleshooting)

### Password Issues

[](#password-issues)

Sometimes, the issue may be due to different encoding types, such as `WINDOWS-CP1251` for Eastern Europe, while the software might input it as `UTF-8`. So, even if the password looks identical, it’s important to use the correct encoding.

### Corrupted or Multipart Archive

[](#corrupted-or-multipart-archive)

The library doesn’t currently handle corruption detection or combining multipart archives. If the file is incompatible, the message will indicate that the password is incorrect.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance66

Regular maintenance activity

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 99.1% 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 ~39 days

Recently: every ~49 days

Total

9

Last Release

320d ago

Major Versions

0.2.0 → 1.0.02025-03-04

### Community

Maintainers

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

---

Top Contributors

[![tabuna](https://avatars.githubusercontent.com/u/5102591?v=4)](https://github.com/tabuna "tabuna (232 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

---

Tags

archivesextractingdecompression

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/esplora-decompresso/health.svg)

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

###  Alternatives

[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[esplora/lumos

PHP library for unlock contents from various files with ease.

12141.9k](/packages/esplora-lumos)[illuminate/filesystem

The Illuminate Filesystem package.

15261.6M2.6k](/packages/illuminate-filesystem)[stechstudio/laravel-zipstream

A fast and simple streaming zip file downloader for Laravel.

4633.7M3](/packages/stechstudio-laravel-zipstream)[spatie/laravel-google-cloud-storage

Google Cloud Storage filesystem driver for Laravel

2408.9M13](/packages/spatie-laravel-google-cloud-storage)[artgris/filemanager-bundle

FileManager is a simple Multilingual File Manager Bundle for Symfony

182420.8k9](/packages/artgris-filemanager-bundle)

PHPackages © 2026

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