Skip to content

Commit 64227ef

Browse files
deemonicdeemonic
authored
Feature/imagick-and-refactor (#5)
* wip mark implementation * wip markdown * added imagick strategy + minor refactor * refactored conversion result * updated tests and added imagick to github workflow * refactored cleanup service * updated readme + added webp and gif support * added tests for gif and webp * adding gif and webp sample files * updated cleanup class tests * updated readme and testcase * added potrace install to the workflow * updated test case
1 parent 3d73f9b commit 64227ef

61 files changed

Lines changed: 1048 additions & 535 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ sample.txt filter=lfs diff=lfs merge=lfs -text
1717
sample.xls filter=lfs diff=lfs merge=lfs -text
1818
sample.xlsx filter=lfs diff=lfs merge=lfs -text
1919
sample.xml filter=lfs diff=lfs merge=lfs -text
20+
sample.gif filter=lfs diff=lfs merge=lfs -text
21+
sample.webp filter=lfs diff=lfs merge=lfs -text

‎.github/workflows/main.yml‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
uses: shivammathur/setup-php@v2
1919
with:
2020
php-version: "8.2"
21-
extensions: mbstring, dom, zip, fileinfo
21+
extensions: mbstring, dom, zip, fileinfo, imagick
2222

2323
# Step 3: Set up Git LFS
2424
- name: Set up Git LFS
@@ -36,22 +36,26 @@ jobs:
3636
- name: Install LibreOffice
3737
run: sudo apt-get update && sudo apt-get install -y libreoffice
3838

39-
# Step 6: Install Composer dependencies
39+
# Step 6: Install Potrace (Required for BMP to SVG conversion)
40+
- name: Install Potrace
41+
run: sudo apt-get install -y potrace
42+
43+
# Step 7: Install Composer dependencies
4044
- name: Install dependencies
4145
run: composer install --no-interaction --prefer-dist
4246

43-
# Step 7: Set up Laravel environment (if needed)
47+
# Step 8: Set up Laravel environment (if needed)
4448
- name: Set up Laravel environment
4549
run: |
4650
echo "APP_KEY=$(php artisan key:generate --show)" > .env
4751
echo "APP_ENV=testing" >> .env
4852
echo "DB_CONNECTION=sqlite" >> .env
4953
echo "LIBREOFFICE_PATH=/usr/bin/soffice" >> .env
5054
51-
# Step 8: Run Unit tests
55+
# Step 9: Run Unit tests
5256
- name: Run Unit tests
5357
run: php ./vendor/bin/phpunit --testsuite=Unit
5458

55-
# Step 9: Run Integration tests (requires LibreOffice)
59+
# Step 10: Run Integration tests (requires LibreOffice)
5660
- name: Run Integration tests
5761
run: php ./vendor/bin/phpunit --testsuite=Integration --testdox

‎README.md‎

Lines changed: 109 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -10,24 +10,25 @@
1010

1111
# Doxswap
1212

13-
A Laravel package for seamless document conversion using LibreOffice. Convert between various document formats like DOCX, PDF, ODT and more with a simple, elegant API.
13+
A Laravel package for seamless document and image format conversions. Transform between various formats like DOCX, PDF, ODT, and popular image formats using a simple, elegant API. Powered by LibreOffice for documents and ImageMagick for image processing.
1414

1515
## 🚀 Features
1616

17-
- 📄 **Multiple Format Support** – Convert between DOCX, PDF, ODT, and other document formats.
18-
- 🚀 **Simple API** – Easy-to-use interface for document conversion operations.
19-
- 💾 **Laravel Storage Integration** – Works seamlessly with Laravel's filesystem drivers.
20-
- ⚡ **Efficient Processing** – Optimized conversion using LibreOffice's powerful engine.
21-
- 🔒 **Secure File Handling** – Safe and secure document processing with proper cleanup.
22-
- ⚙️ **Configurable Settings** – Customize paths, storage disks, and conversion options.
23-
- 🛡️ **Error Handling** – Robust exception handling for unsupported formats and conversions.
17+
- 📄 **Multiple Format Support** – Convert between documents (DOCX, PDF, ODT) and images (PNG, JPG, WEBP) with ease
18+
- 🚀 **Simple API** – Easy-to-use interface for all conversion operations
19+
- 💾 **Laravel Storage Integration** – Works seamlessly with Laravel's filesystem drivers
20+
- ⚡ **Efficient Processing** – Optimized conversion using LibreOffice and ImageMagick engines
21+
- 🔍 **Conversion Tracking** – Detailed results including duration and file paths
22+
- 🔒 **Secure File Handling** – Safe and secure file processing with proper cleanup
23+
- ⚙️ **Configurable Settings** – Customize paths, storage disks, and conversion options
24+
- 🛡️ **Error Handling** – Robust exception handling for unsupported formats and conversions
2425

2526
## Installation
2627

2728
You can install the package via composer:
2829

2930
```bash
30-
composer require blaspsoft/doxswap:0.1.0-beta
31+
composer require blaspsoft/doxswap
3132
```
3233

3334
You can publish the config file with:
@@ -40,19 +41,43 @@ php artisan vendor:publish --tag="doxswap-config"
4041

4142
The `config/doxswap.php` file includes:
4243

43-
#### 💾 Storage
44+
#### 💾 Storage & Cleanup
4445

4546
- `input_disk`: Where to read files from (default: 'public')
4647
- `output_disk`: Where to save converted files (default: 'public')
4748
- `perform_cleanup`: Delete input files after conversion (default: false)
4849

49-
#### 🛠️ LibreOffice Path
50+
#### 📝 File Naming
51+
52+
Configure how output files are named using different strategies:
53+
54+
```php
55+
'filename' => [
56+
// Strategy: 'original', 'random', or 'timestamp'
57+
'strategy' => 'original',
58+
59+
// Naming options
60+
'options' => [
61+
'length' => 24, // Length for random names
62+
'prefix' => '', // Add prefix to filename
63+
'suffix' => '', // Add suffix to filename
64+
'separator' => '_', // Separator for components
65+
'format' => 'YmdHis', // Format for timestamp strategy
66+
],
67+
]
68+
```
69+
70+
#### 🛠️ Conversion Drivers
71+
72+
Configure paths for conversion tools:
5073

5174
```php
52-
'libre_office_path' => env('LIBRE_OFFICE_PATH', '/usr/bin/soffice')
75+
'drivers' => [
76+
'libreoffice_path' => env('LIBRE_OFFICE_PATH', '/usr/bin/soffice'),
77+
]
5378
```
5479

55-
Default paths by OS:
80+
Default LibreOffice paths by OS:
5681

5782
- 🐧 Linux: `/usr/bin/soffice`
5883
- 🍎 macOS: `/Applications/LibreOffice.app/Contents/MacOS/soffice`
@@ -65,113 +90,130 @@ Supports various document formats including:
6590
- Documents: DOC, DOCX, ODT, RTF, TXT
6691
- Spreadsheets: XLS, XLSX, ODS, CSV
6792
- Presentations: PPT, PPTX, ODP
68-
- Images: JPG, PNG, SVG, BMP, TIFF
93+
- Images: JPG, PNG, SVG, BMP, TIFF, WEBP, GIF
6994
- Web: HTML, XML
70-
- Other: PDF, EPUB
95+
- Other: PDF
7196

7297
### Usage
7398

7499
```php
75-
$convertedFile = Doxswap::convert('sample.docx', 'pdf');
100+
$result = Doxswap::convert('sample.docx', 'pdf');
76101

77102
/**
78-
* Returns a Doxswap object with the following properties:
103+
* Returns a ConversionResult object with the following properties:
79104
*
80-
* @property string $inputFile The original input filename
81-
* @property string $outputFile The full path to the converted output file
82-
* @property string $toFormat The format the file was converted to (e.g. 'pdf')
83-
* @property ConversionService $conversionService The service used for conversion
105+
* @property string $inputFilename The original input filename
106+
* @property string $inputFilePath The full path to the input file
107+
* @property string $outputFilename The converted output filename
108+
* @property string $outputFilePath The full path to the converted output file
109+
* @property string $toFormat The format the file was converted to (e.g. 'pdf')
110+
* @property string $duration The time taken for conversion (e.g. "2.21 sec")
111+
* @property float $startTime Unix timestamp of when conversion started
112+
* @property float $endTime Unix timestamp of when conversion completed
113+
* @property string $inputDisk The Laravel storage disk used for input
114+
* @property string $outputDisk The Laravel storage disk used for output
84115
*/
85116

86117
```
87118

88119
## Requirements
89120

90-
### LibreOffice
121+
### LibreOffice & ImageMagick
91122

92-
This package requires LibreOffice to be installed on your system. Here's how to install it:
123+
This package requires LibreOffice and ImageMagick to be installed on your system. Here's how to install them:
93124

94125
#### Ubuntu/Debian
95126

96127
```bash
97128
sudo apt update
98-
sudo apt install libreoffice
129+
sudo apt install libreoffice imagemagick
99130
```
100131

101132
#### macOS
102133

103134
```bash
104-
brew install libreoffice
135+
brew install libreoffice imagemagick
105136
```
106137

107-
# or download from https://www.libreoffice.org/download/download-libreoffice/
138+
# or download LibreOffice from https://www.libreoffice.org/download/download-libreoffice/
108139

109140
#### Windows
110141

111142
```bash
112-
choco install libreoffice
143+
choco install libreoffice imagemagick
113144
```
114145

115-
# or download from https://www.libreoffice.org/download/download-libreoffice/
146+
# or download LibreOffice from https://www.libreoffice.org/download/download-libreoffice/
116147

117148
#### Docker
118149

119-
If you're using Docker, you can add LibreOffice to your container:
150+
If you're using Docker, you can add the required dependencies to your container:
120151

121152
```dockerfile
122153
# Ubuntu/Debian based
123-
RUN apt-get update && apt-get install -y libreoffice
154+
RUN apt-get update && apt-get install -y libreoffice imagemagick
124155

125156
# Alpine based
126-
RUN apk add --no-cache libreoffice
157+
RUN apk add --no-cache libreoffice imagemagick
127158
```
128159

129160
### PHP Requirements
130161

131162
- PHP >= 8.1
132163
- ext-fileinfo
164+
- ext-imagick
133165
- Laravel >= 9.0
134166

135-
## Supported Conversions 📄 ↔️ 📑
136-
137-
| From/To | PDF | DOCX | ODT | RTF | TXT | HTML | EPUB | XML | XLSX | ODS | CSV | PPT | PPTX | ODP | PNG | JPG | SVG | TIFF |
138-
| ------- | :-: | :--: | :-: | :-: | :-: | :--: | :--: | :-: | :--: | :-: | :-: | :-: | :--: | :-: | :-: | :-: | :-: | :--: |
139-
| DOC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | | | | | | | | |
140-
| DOCX | ✅ | | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | | | | | | | | | |
141-
| ODT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ✅ | | | | | | | | | | |
142-
| RTF | ✅ | ✅ | ✅ | | ✅ | ✅ | | ✅ | | | | | | | | | | |
143-
| TXT | ✅ | ✅ | ✅ | | | ✅ | | ✅ | | | | | | | | | | |
144-
| HTML | ✅ | | ✅ | | ✅ | | | | | | | | | | | | | |
145-
| XML | ✅ | ✅ | ✅ | | ✅ | ✅ | | | | | | | | | | | | |
146-
| CSV | ✅ | | | | | ✅ | | | ✅ | ✅ | | | | | | | | |
147-
| XLSX | ✅ | | | | | ✅ | | | | ✅ | ✅ | | | | | | | |
148-
| XLS | ✅ | | | | | ✅ | | | | ✅ | ✅ | | | | | | | |
149-
| ODS | ✅ | | | | | ✅ | | | ✅ | | ✅ | | | | | | | |
150-
| PPTX | ✅ | | | | | | | | | | | | | ✅ | | | | |
151-
| PPT | ✅ | | | | | | | | | | | | | ✅ | | | | |
152-
| ODP | ✅ | | | | | | | | | | | | ✅ | | | | | |
153-
| SVG | ✅ | | | | | | | | | | | | | | ✅ | ✅ | | ✅ |
154-
| JPG | ✅ | | | | | | | | | | | | | | ✅ | | ✅ | |
155-
| PNG | ✅ | | | | | | | | | | | | | | | ✅ | ✅ | |
156-
| BMP | ✅ | | | | | | | | | | | | | | ✅ | ✅ | | |
157-
| TIFF | ✅ | | | | | | | | | | | | | | ✅ | ✅ | | |
167+
## 🔁 Supported Conversions by Category
168+
169+
### 📝 Documents
170+
171+
| From | Supported Conversions |
172+
| ---- | ---------------------------------------------- |
173+
| DOCX | PDF ✅✅, ODT, RTF, TXT, HTML, XML, EPUB |
174+
| DOC | PDF ✅✅, DOCX, ODT, RTF, TXT, HTML, XML, EPUB |
175+
| ODT | PDF, DOCX, RTF, TXT, HTML, XML |
176+
| RTF | PDF, DOCX, ODT, TXT, HTML, XML |
177+
| TXT | PDF, DOCX, ODT, HTML, XML |
178+
| HTML | PDF, ODT, TXT |
179+
| XML | PDF, DOCX, ODT, TXT, HTML |
180+
181+
### 📊 Spreadsheets
182+
183+
| From | Supported Conversions |
184+
| ---- | --------------------- |
185+
| XLSX | PDF ✅✅, ODS, CSV |
186+
| XLS | PDF, XLSX, ODS, CSV |
187+
| ODS | PDF, XLSX, CSV |
188+
| CSV | PDF, XLSX, ODS |
189+
190+
### 🎯 Presentations
191+
192+
| From | Supported Conversions |
193+
| ---- | --------------------- |
194+
| PPTX | PDF ✅✅, ODP |
195+
| PPT | PDF, PPTX, ODP |
196+
| ODP | PDF, PPTX |
197+
198+
### 🖼️ Images
199+
200+
| From | Supported Conversions |
201+
| ---- | -------------------------------------- |
202+
| PNG | PDF ✅, JPG, SVG, TIFF, WEBP, GIF, BMP |
203+
| JPG | PDF ✅, PNG, SVG, TIFF, WEBP, GIF, BMP |
204+
| SVG | PDF, PNG, JPG, TIFF, WEBP, GIF, BMP |
205+
| BMP | PDF, PNG, JPG, SVG, TIFF, WEBP, GIF |
206+
| TIFF | PDF, PNG, JPG, SVG, WEBP, GIF, BMP |
207+
| WEBP | PDF, PNG, JPG, SVG, TIFF, GIF, BMP |
208+
| GIF | PDF, PNG, JPG, SVG, TIFF, WEBP, BMP |
158209

159210
### Legend 🔍
160211

161-
- ✅ : Supported conversion
162-
- Empty cell: Conversion not supported
163-
164-
### File Type Categories 📁
165-
166-
- 📝 Documents: DOC, DOCX, ODT, RTF, TXT
167-
- 🌐 Web: HTML, XML
168-
- 📊 Spreadsheets: XLSX, XLS, ODS, CSV
169-
- 🎯 Presentations: PPT, PPTX, ODP
170-
- 🖼️ Images: SVG, JPG, PNG, BMP, TIFF
171-
- 📚 eBooks: EPUB
172-
- 📄 Universal: PDF
212+
- ✅✅ = Common high-priority conversion
213+
- ✅ = Popular supported format
214+
- (unlisted) = Conversion not supported
173215

174-
> **Note**: All conversions are performed using LibreOffice in headless mode 🚀
216+
> **Note**: Document conversions are performed using LibreOffice in headless mode, while image format conversions utilize ImageMagick 🚀
175217
176218
## License
177219

‎config/config.php‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,19 +24,13 @@
2424

2525
/*
2626
|--------------------------------------------------------------------------
27-
| Cleanup Strategy
27+
| Cleanup
2828
|--------------------------------------------------------------------------
2929
|
30-
| Here you may specify the cleanup strategy to use.
31-
|
32-
| Supported strategies:
33-
| - none: No cleanup is performed.
34-
| - input: Only the input file is deleted.
35-
| - output: Only the output file is deleted.
36-
| - both: Both the input and output files are deleted.
30+
| Here you may specify if the input file should be deleted after the conversion.
3731
|
3832
*/
39-
'cleanup_strategy' => 'none',
33+
'perform_cleanup' => false,
4034

4135
/*
4236
|--------------------------------------------------------------------------
@@ -98,11 +92,9 @@
9892
|
9993
| Supported drivers:
10094
| - libreoffice: The LibreOffice driver.
101-
| - pandoc: The Pandoc driver.
10295
|
10396
*/
10497
'drivers' => [
10598
'libreoffice_path' => env('LIBRE_OFFICE_PATH', '/usr/bin/soffice'),
106-
'pandoc_path' => env('PANDOC_PATH', '/usr/bin/pandoc'),
10799
],
108100
];

‎src/Contracts/ConversionStrategy.php‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
namespace Blaspsoft\Doxswap\Contracts;
44

5+
use Blaspsoft\Doxswap\ConversionResult;
6+
57
interface ConversionStrategy
68
{
79
/**
@@ -10,7 +12,7 @@ interface ConversionStrategy
1012
* @param string $inputFile
1113
* @param string $fromFormat
1214
* @param string $toFormat
13-
* @return string
15+
* @return \Blaspsoft\Doxswap\ConversionResult
1416
*/
15-
public function convert(string $inputFile, string $fromFormat, string $toFormat): string;
17+
public function convert(string $inputFile, string $fromFormat, string $toFormat): ConversionResult;
1618
}

‎src/Contracts/ConvertibleFormat.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
namespace Blaspsoft\Doxswap\Contracts;
44

5+
use Blaspsoft\Doxswap\ConversionResult;
6+
57
interface ConvertibleFormat
68
{
79
public function getName(): string;
@@ -12,5 +14,5 @@ public function getSupportedConversions(): array;
1214

1315
public function getDriver(): ConversionStrategy;
1416

15-
public function convert(string $inputFile, string $toFormat): string;
17+
public function convert(string $inputFile, string $toFormat): ConversionResult;
1618
}

0 commit comments

Comments
 (0)