Download the PHP package esplora/decompresso without Composer

Lumos

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?

• 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.
• Utilize online services for removing passwords or recovering them through methods like brute force.

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:

Installation

Install the library using Composer:

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:

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

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.

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 as a source of popular passwords for brute-forcing.

Extending File Support

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:

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:

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

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:

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

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

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.