esplora / decompresso
PHP library for unlock contents from various files with ease.
Requires
- illuminate/support: ^11.0
- symfony/mime: ^7.1
- symfony/process: ^7.1
Requires (Dev)
- laravel/pint: ^1.17
- phpunit/phpunit: ^10.5
- symfony/var-dumper: ^7.1
- vlucas/phpdotenv: ^5.4.1
This package is auto-updated.
Last update: 2024-11-18 20:45:03 UTC
README
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?
- Unlocking password-protected documents and archives before data extraction with tools like Apache Tika.
- Online services for removing or attempting password recovery, such as through brute force.
External Dependencies
Lumos relies on the following third-party tools for specific operations.
Each adapter is provided out of the box in the Esplora\Lumos\Adapters\*
namespace:
Installation
Install the library using Composer:
composer require esplora/lumos
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 or use built-in ones.
use Esplora\Lumos\Extractor; use Esplora\Lumos\Adapters\SevenZipAdapter; $lumos = Extractor::make() ->withAdapters([ 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
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\SevenZipAdapter; use Esplora\Lumos\Providers\ArrayPasswordProvider; $passwords = new ArrayPasswordProvider([ 'qwerty', 'xxx123', ]); Extractor::make() ->withAdapters([ new SevenZipAdapter(), ]) ->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 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:
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. * * @param string $filePath The file path. * @return bool True if supported, otherwise false. */ public function canSupport(string $filePath): bool { return str_ends_with($filePath, '.custom'); } /** * Checks if the environment is properly configured. * * @return bool True if configured, otherwise false. */ public function isSupportedEnvironment(): bool { return true; // Check external dependencies here } /** * Extracts the content to the specified directory. * * @param string $filePath The file path. * @param string $destination The extraction destination. * @param PasswordProviderInterface $passwords Password provider. * @return SummaryInterface The extraction result. */ public function extract(string $filePath, string $destination, PasswordProviderInterface $passwords): SummaryInterface { // Implement extraction logic here } }
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.
License
The MIT License (MIT). Please see License File for more information.