https://github.com/blaspsoft/doxswap
📄 🔄 Doxswap is a Laravel package for seamless document conversion using LibreOffice. Effortlessly convert DOCX, PDF, ODT, and more with a simple, elegant API. Supports Laravel storage, configurable settings, and secure file handling.
https://github.com/blaspsoft/doxswap
converter document-conversion document-converter docx file-conversion laravel libreoffice odt pdf php xlsx
Last synced: about 2 months ago
JSON representation
📄 🔄 Doxswap is a Laravel package for seamless document conversion using LibreOffice. Effortlessly convert DOCX, PDF, ODT, and more with a simple, elegant API. Supports Laravel storage, configurable settings, and secure file handling.
- Host: GitHub
- URL: https://github.com/blaspsoft/doxswap
- Owner: Blaspsoft
- License: mit
- Created: 2025-03-04T08:11:30.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-26T14:38:54.000Z (3 months ago)
- Last Synced: 2025-04-20T05:43:45.903Z (about 2 months ago)
- Topics: converter, document-conversion, document-converter, docx, file-conversion, laravel, libreoffice, odt, pdf, php, xlsx
- Language: PHP
- Homepage:
- Size: 119 KB
- Stars: 200
- Watchers: 5
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Doxswap
A Laravel package for seamless document and image format conversions. Transform between various formats like DOCX -> PDF, HTML -> PDF, PNG -> WEBP, and more popular formats using a simple, elegant API. Powered by LibreOffice for documents and ImageMagick for image processing.
## 🚀 Features
- 📄 **Multiple Format Support** – Convert between documents (DOCX, XLSX, ODT) and images (PNG, JPG, WEBP) with ease
- 🚀 **Simple API** – Easy-to-use interface for all conversion operations
- 💾 **Laravel Storage Integration** – Works seamlessly with Laravel's filesystem drivers
- ⚡ **Efficient Processing** – Optimized conversion using LibreOffice and ImageMagick engines
- 🔍 **Conversion Tracking** – Detailed results including duration and file paths
- 🔒 **Secure File Handling** – Safe and secure file processing with proper cleanup
- ⚙️ **Configurable Settings** – Customize paths, storage disks, and conversion options
- 🛡️ **Error Handling** – Robust exception handling for unsupported formats and conversions
## Installation
You can install the package via composer:
```bash
composer require blaspsoft/doxswap
```
You can publish the config file with:
```bash
php artisan vendor:publish --tag="doxswap-config"
```
### Overview
The `config/doxswap.php` file includes:
#### 💾 Storage & Cleanup
- `input_disk`: Where to read files from (default: 'public')
- `output_disk`: Where to save converted files (default: 'public')
- `perform_cleanup`: Delete input files after conversion (default: false)
#### 📝 File Naming
Configure how output files are named using different strategies:
```php
'filename' => [
// Strategy: 'original', 'random', or 'timestamp'
'strategy' => 'original',
// Naming options
'options' => [
'length' => 24, // Length for random names
'prefix' => '', // Add prefix to filename
'suffix' => '', // Add suffix to filename
'separator' => '_', // Separator for components
'format' => 'YmdHis', // Format for timestamp strategy
],
]
```
#### 🛠️ Conversion Drivers
Configure paths for conversion tools:
```php
'drivers' => [
'libreoffice_path' => env('LIBRE_OFFICE_PATH', '/usr/bin/soffice'),
]
```
Default LibreOffice paths by OS:
- 🐧 Linux: `/usr/bin/soffice`
- 🍎 macOS: `/Applications/LibreOffice.app/Contents/MacOS/soffice`
- 🪟 Windows: `C:\Program Files\LibreOffice\program\soffice.exe`
#### 📄 File Types
Supports various document formats including:
- Documents: DOC, DOCX, ODT, RTF, TXT
- Spreadsheets: XLS, XLSX, ODS, CSV
- Presentations: PPT, PPTX, ODP
- Images: JPG, PNG, SVG, BMP, TIFF, WEBP, GIF
- Web: HTML, XML
- Other: PDF
### Usage
```php
$result = Doxswap::convert('sample.docx', 'pdf');
/**
* Returns a ConversionResult object with the following properties:
*
* @property string $inputFilename The original input filename
* @property string $inputFilePath The full path to the input file
* @property string $outputFilename The converted output filename
* @property string $outputFilePath The full path to the converted output file
* @property string $toFormat The format the file was converted to (e.g. 'pdf')
* @property string $duration The time taken for conversion (e.g. "2.21 sec")
* @property float $startTime Unix timestamp of when conversion started
* @property float $endTime Unix timestamp of when conversion completed
* @property string $inputDisk The Laravel storage disk used for input
* @property string $outputDisk The Laravel storage disk used for output
*/
```
## Requirements
### LibreOffice & ImageMagick
This package requires LibreOffice, ImageMagick, and Potrace to be installed on your system. Here's how to install them:
#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install libreoffice imagemagick potrace
```
#### macOS
```bash
brew install libreoffice imagemagick potrace
```
#### Windows
```bash
choco install libreoffice imagemagick potrace
```
#### Docker
If you're using Docker, you can add the required dependencies to your container:
```dockerfile
# Ubuntu/Debian based
RUN apt-get update && apt-get install -y libreoffice imagemagick potrace
# Alpine based
RUN apk add --no-cache libreoffice imagemagick potrace
```
### PHP Requirements
- PHP >= 8.1
- ext-fileinfo
- ext-imagick
- Laravel >= 9.0
## 🔁 Supported Conversions by Category
### 📝 Documents
| From | Supported Conversions |
| ---- | ---------------------------------------------- |
| DOCX | PDF ✅✅, ODT, RTF, TXT, HTML, XML, EPUB |
| DOC | PDF ✅✅, DOCX, ODT, RTF, TXT, HTML, XML, EPUB |
| ODT | PDF, DOCX, RTF, TXT, HTML, XML |
| RTF | PDF, DOCX, ODT, TXT, HTML, XML |
| TXT | PDF, DOCX, ODT, HTML, XML |
| HTML | PDF, ODT, TXT |
| XML | PDF, DOCX, ODT, TXT, HTML |
### 📊 Spreadsheets
| From | Supported Conversions |
| ---- | --------------------- |
| XLSX | PDF ✅✅, ODS, CSV |
| XLS | PDF, XLSX, ODS, CSV |
| ODS | PDF, XLSX, CSV |
| CSV | PDF, XLSX, ODS |
### 🎯 Presentations
| From | Supported Conversions |
| ---- | --------------------- |
| PPTX | PDF ✅✅, ODP |
| PPT | PDF, PPTX, ODP |
| ODP | PDF, PPTX |
### 🖼️ Images
| From | Supported Conversions |
| ---- | -------------------------------------- |
| PNG | PDF ✅, JPG, SVG, TIFF, WEBP, GIF, BMP |
| JPG | PDF ✅, PNG, SVG, TIFF, WEBP, GIF, BMP |
| SVG | PDF, PNG, JPG, TIFF, WEBP, GIF, BMP |
| BMP | PDF, PNG, JPG, SVG, TIFF, WEBP, GIF |
| TIFF | PDF, PNG, JPG, SVG, WEBP, GIF, BMP |
| WEBP | PDF, PNG, JPG, SVG, TIFF, GIF, BMP |
| GIF | PDF, PNG, JPG, SVG, TIFF, WEBP, BMP |
### Legend 🔍
- ✅✅ = Common high-priority conversion
- ✅ = Popular supported format
- (unlisted) = Conversion not supported
> **Note**: Document conversions are performed using LibreOffice in headless mode, while image format conversions utilize ImageMagick 🚀
## 🤝 Sponsors
If you find this package helpful, please consider sponsoring the development:
> 🚀 [Become a GitHub Sponsor](https://github.com/sponsors/Blaspsoft)
## License
Blasp is open-sourced software licensed under the [MIT license](LICENSE).