Merge pull request #230 from spatie/v3

Major version: v3.0
spatie · Jun 10, 2024 · b145cf4 · b145cf4
2 parents 61ea9a6 + 7a68ada
commit b145cf4
Show file tree

Hide file tree

Showing 30 changed files with 756 additions and 316 deletions.
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
@@ -1 +1,2 @@
 github: spatie
+custom: https://spatie.be/open-source/support-us
diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml
@@ -13,7 +13,7 @@ jobs:
 
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2.1.0
+        uses: dependabot/fetch-metadata@v2
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
           compat-lookup: true

diff --git a/.github/workflows/php-cs-fixer.yml → .github/workflows/pint.yml b/.github/workflows/php-cs-fixer.yml → .github/workflows/pint.yml
@@ -12,12 +12,10 @@ jobs:
         with:
           ref: ${{ github.head_ref }}
 
-      - name: Run PHP CS Fixer
-        uses: docker://oskarstark/php-cs-fixer-ga
-        with:
-          args: --config=.php-cs-fixer.dist.php --allow-risky=yes
+      - name: Fix styling issues
+        uses: aglipanci/laravel-pint-action@v2
 
       - name: Commit changes
-        uses: stefanzweifel/git-auto-commit-action@v4
+        uses: stefanzweifel/git-auto-commit-action@v5
         with:
           commit_message: Fix styling
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -8,7 +8,7 @@ jobs:
         strategy:
             fail-fast: true
             matrix:
-                php: [8.3, 8.2, 8.1, 8.0, 7.4]
+                php: [8.3, 8.2]
                 dependency-version: [prefer-lowest, prefer-stable]
                 os: [ubuntu-latest]
 

diff --git a/.php-cs-fixer.dist.php b/.php-cs-fixer.dist.php
diff --git a/.github/LICENSE.md → LICENSE.md b/.github/LICENSE.md → LICENSE.md
diff --git a/README.md b/README.md
@@ -1,75 +1,141 @@
-# Convert a pdf to an image
+# Convert a PDF to an image
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/pdf-to-image.svg?style=flat-square)](https://packagist.org/packages/spatie/pdf-to-image)
-[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](.github/LICENSE.md)
+[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
 [![Quality Score](https://img.shields.io/scrutinizer/g/spatie/pdf-to-image.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/pdf-to-image)
-[![StyleCI](https://styleci.io/repos/38419604/shield?branch=master)](https://styleci.io/repos/38419604)
 [![Total Downloads](https://img.shields.io/packagist/dt/spatie/pdf-to-image.svg?style=flat-square)](https://packagist.org/packages/spatie/pdf-to-image)
 
-This package provides an easy to work with class to convert PDF's to images.
-
-Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource).
-
-## Support us
-
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/pdf-to-image.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/pdf-to-image)
-
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
-
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+This package provides an easy-to-work-with class to convert a PDF to one or more image.
 
 ## Requirements
 
-You should have [Imagick](http://php.net/manual/en/imagick.setresolution.php) and [Ghostscript](http://www.ghostscript.com/) installed. See [issues regarding Ghostscript](#issues-regarding-ghostscript).
+You should have [Imagick](http://php.net/manual/en/imagick.setresolution.php) and [Ghostscript](http://www.ghostscript.com/) installed. 
+See [issues regarding Ghostscript](#issues-regarding-ghostscript) and [Imagick Issues](#imagick-issues) for more information.
 
 ## Installation
 
-The package can be installed via composer:
-``` bash
+The package can be installed via composer and requires PHP 8.2+:
+
+```bash
 composer require spatie/pdf-to-image
 ```
 
+> If you are using PHP < 8.2, use version 2.0 of this package.
+
 ## Usage
 
-Converting a pdf to an image is easy.
+Converting a PDF to an image is easy.
 
 ```php
-$pdf = new Spatie\PdfToImage\Pdf($pathToPdf);
-$pdf->saveImage($pathToWhereImageShouldBeStored);
+$pdf = new \Spatie\PdfToImage\Pdf($pathToPdf);
+$pdf->save($pathToWhereImageShouldBeStored);
 ```
 
-If the path you pass to `saveImage` has the extensions `jpg`, `jpeg`, or `png` the image will be saved in that format.
-Otherwise the output will be a jpg.
+If the filename you pass to `saveImage` has the extensions `jpg`, `jpeg`, `png`, or `webp` the image will be saved in that format; otherwise the output format will be `jpg`.
+
+The `save()` method returns an array with the filenames of the saved images if multiple images are saved, otherwise returns a string with the path to the saved image.
 
 ## Other methods
 
-You can get the total number of pages in the pdf:
+Get the total number of pages in the pdf:
+
+```php
+/** @var int $numberOfPages */
+$numberOfPages = $pdf->pageCount();
+```
+
+Check if a file type is a supported output format:
+
+```php
+/** @var bool $isSupported */
+$isSupported = $pdf->isValidOutputFormat('jpg');
+```
+
+By default, only the first page of the PDF will be rendered. To render another page, call the `selectPage()` method:
+
 ```php
-$pdf->getNumberOfPages(); //returns an int
+$pdf->selectPage(2)
+    ->save($pathToWhereImageShouldBeStored); //saves the second page
 ```
 
-By default the first page of the pdf will be rendered. If you want to render another page you can do so:
+Or, select multiple pages with the `selectPages()` method:
+
 ```php
-$pdf->setPage(2)
-    ->saveImage($pathToWhereImageShouldBeStored); //saves the second page
+$pdf->selectPages(2, 4, 5)
+    ->save($directoryToWhereImageShouldBeStored); //saves the 2nd, 4th and 5th pages
 ```
 
-You can override the output format:
+Change the output format:
+
 ```php
-$pdf->setOutputFormat('png')
-    ->saveImage($pathToWhereImageShouldBeStored); //the output wil be a png, no matter what
+$pdf->format(\Spatie\PdfToImage\Enums\OutputFormat::Webp)
+    ->save($pathToWhereImageShouldBeStored); //the saved image will be in webp format
 ```
 
-You can set the quality of compression from 0 to 100:
+Set the output quality _(the compression quality)_ from 0 to 100:
+
 ```php
-$pdf->setCompressionQuality(100); // sets the compression quality to maximum
+$pdf->quality(90) // set an output quality of 90%
+    ->save($pathToWhereImageShouldBeStored);
 ```
 
-You can specify the width of the resulting image:
+Set the output resolution DPI:
+
+```php
+$pdf->resolution(300) // resolution of 300 dpi
+    ->save($pathToWhereImageShouldBeStored);
+```
+
+Specify the thumbnail size of the output image:
+
 ```php
 $pdf
-   ->width(400)
-   ->saveImage($pathToWhereImageShouldBeStored);
+   ->thumbnailSize(400) // set thumbnail width to 400px; height is calculated automatically
+   ->save($pathToWhereImageShouldBeStored);
+
+// or:
+$pdf
+   ->thumbnailSize(400, 300) // set thumbnail width to 400px and the height to 300px
+   ->save($pathToWhereImageShouldBeStored);
+```
+
+Set the output image width:
+
+```php
+$pdf->size(400) // set the width to 400px; height is calculated automatically
+    ->save($pathToWhereImageShouldBeStored);
+```
+
+Set the output image width and height:
+
+```php
+$pdf->size(400, 300) // set the width to 400px and the height to 300px
+    ->save($pathToWhereImageShouldBeStored);
+```
+
+Get the dimensions of the PDF. This can be used to determine if the PDF is extremely high-resolution.
+
+```php
+/** @var \Spatie\PdfToImage\DTOs\PageSize $size */
+$size = $pdf->getSize();
+
+$width = $size->width;
+$height = $size->height;
+```
+
+Save all pages to images:
+
+```php
+$pdf->saveAllPages($directoryToWhereImagesShouldBeStored);
+```
+
+Set the Merge Layer Method for Imagick:
+
+```php
+$pdf->layerMethod(\Spatie\PdfToImage\Enums\LayerMethod::Merge);
+
+// or disable layer merging:
+$pdf->layerMethod(\Spatie\PdfToImage\Enums\LayerMethod::None);
 ```
 
 ## Issues regarding Ghostscript
@@ -90,37 +156,40 @@ env[PATH] = /usr/local/bin:/usr/bin:/bin
 
 This will instruct PHP FPM to look for the `gs` binary in the right places.
 
+## Imagick Issues
+
+If you receive an error with the message `attempt to perform an operation not allowed by the security policy 'PDF'`, you may need to add the following line to your `policy.xml` file. This file is usually located in `/etc/ImageMagick-[VERSION]/policy.xml`, such as `/etc/ImageMagick-7/policy.xml`.
+
+```xml
+<policy domain="coder" rights="read | write" pattern="PDF" />
+```
+
 ## Testing
 
+`spatie/pdf-to-image` uses the PEST framework for unit tests. They can be run with the following command:
+
 ``` bash
-composer test
+./vendor/bin/pest
 ```
 
 ## Changelog
 
-Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
+Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
 ## Contributing
 
 Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.
 
-## Security
-
-If you've found a bug regarding security please mail [[email protected]](mailto:[email protected]) instead of using the issue tracker.
-
-## Postcardware
-
-You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.
-
-Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.
+## Security Vulnerabilities
 
-We publish all received postcards [on our company website](https://spatie.be/en/opensource/postcards).
+Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
 
 ## Credits
 
-- [Freek Van der Herten](https://github.com/spatie)
+- [Freek Van der Herten](https://github.com/freekmurze)
+- [Patrick Organ](https://github.com/patinthehat)
 - [All Contributors](../../contributors)
 
 ## License
 
-The MIT License (MIT). Please see [License File](.github/LICENSE.md) for more information.
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
diff --git a/composer.json b/composer.json
@@ -16,14 +16,20 @@
             "email": "[email protected]",
             "homepage": "https://spatie.be",
             "role": "Developer"
+        },
+        {
+            "name": "Patrick Organ",
+            "email": "[email protected]",
+            "homepage": "https://permafrost.dev",
+            "role": "Developer"
         }
     ],
     "require": {
-        "php" : "^7.2|^8.0",
+        "php" : "^8.2",
         "ext-imagick" : "*"
     },
     "require-dev": {
-        "pestphp/pest": "^1.21"
+        "pestphp/pest": "^2.34"
     },
     "autoload": {
         "psr-4": {

diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -1,29 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="vendor/autoload.php"
-         backupGlobals="false"
-         backupStaticAttributes="false"
-         colors="true"
-         verbose="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false">
-    <testsuites>
-        <testsuite name="League Test Suite">
-            <directory>tests</directory>
-        </testsuite>
-    </testsuites>
-    <filter>
-        <whitelist>
-            <directory suffix=".php">src/</directory>
-        </whitelist>
-    </filter>
-    <logging>
-        <log type="tap" target="build/report.tap"/>
-        <log type="junit" target="build/report.junit.xml"/>
-        <log type="coverage-html" target="build/coverage"/>
-        <log type="coverage-text" target="build/coverage.txt"/>
-        <log type="coverage-clover" target="build/logs/clover.xml"/>
-    </logging>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" backupGlobals="false" colors="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd" cacheDirectory=".phpunit.cache" backupStaticProperties="false">
+  <coverage>
+    <report>
+      <clover outputFile="build/logs/clover.xml"/>
+      <html outputDirectory="build/coverage"/>
+      <text outputFile="build/coverage.txt"/>
+    </report>
+  </coverage>
+  <testsuites>
+    <testsuite name="League Test Suite">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+  <logging>
+    <junit outputFile="build/report.junit.xml"/>
+  </logging>
+  <source>
+    <include>
+      <directory suffix=".php">src/</directory>
+    </include>
+  </source>
 </phpunit>