PHPackages                             arthurhoaro/web-thumbnailer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. arthurhoaro/web-thumbnailer

ActiveLibrary[Image & Media](/categories/media)

arthurhoaro/web-thumbnailer
===========================

PHP library which will retrieve a thumbnail for any given URL

v2.2.0(3y ago)2225.0k↓48.8%2[1 PRs](https://github.com/ArthurHoaro/web-thumbnailer/pulls)MITPHPPHP >=7.1

Since Nov 11Pushed 3y ago4 watchersCompare

[ Source](https://github.com/ArthurHoaro/web-thumbnailer)[ Packagist](https://packagist.org/packages/arthurhoaro/web-thumbnailer)[ RSS](/packages/arthurhoaro-web-thumbnailer/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (20)Used By (0)

Web Thumbnailer
===============

[](#web-thumbnailer)

[![](https://camo.githubusercontent.com/301b1838d78f325d9b5432ee550eb41b473f870e97c58f134dd21d87f58b41e5/68747470733a2f2f7472617669732d63692e6f72672f417274687572486f61726f2f7765622d7468756d626e61696c65722e7376673f6272616e63683d6d6173746572)](https://camo.githubusercontent.com/301b1838d78f325d9b5432ee550eb41b473f870e97c58f134dd21d87f58b41e5/68747470733a2f2f7472617669732d63692e6f72672f417274687572486f61726f2f7765622d7468756d626e61696c65722e7376673f6272616e63683d6d6173746572)[![Coverage Status](https://camo.githubusercontent.com/7b8eddb8128b975829f2af24738750cea7e2b3bb2d3b35e8b64428f69f7c29f4/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f417274687572486f61726f2f7765622d7468756d626e61696c65722f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/ArthurHoaro/web-thumbnailer?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/44ad99b8817067f19463336612208b2c040da754b4bfdeaae1cc179561f17c06/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f417274687572486f61726f2f7765622d7468756d626e61696c65722f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/ArthurHoaro/web-thumbnailer/?branch=master)

PHP library which will retrieve a thumbnail for any given URL, if available.

Features
--------

[](#features)

- Support various specific website features: Imgur, FlickR, Youtube, XKCD, etc.
- Work with any website supporting [OpenGraph](http://ogp.me/) (tag meta `og:image`)
- Or use direct link to images
- Local cache
- Resizing and/or cropping according to given settings

Requirements
------------

[](#requirements)

Mandatory:

- PHP 7.1 (`v2.0.0`+) - PHP 5.6 (`v1.x.x`)
- PHP GD extension

(Highly) Recommended:

- PHP cURL extension: it let you retrieve thumbnails without downloading the whole remote page

Installation
------------

[](#installation)

Using [Composer](https://getcomposer.org/):

```
composer require arthurhoaro/web-thumbnailer
```

Usage
-----

[](#usage)

Using WebThumbnailer is pretty straight forward:

```
require_once 'vendor/autoload.php';

use WebThumbnailer\WebThumbnailer;

$wt = new WebThumbnailer();

// Very basic usage
$thumb = $wt->thumbnail('https://github.com/ArthurHoaro');

// Using a bit of configuration
$thumb2 = $wt->maxHeight(180)
            ->maxWidth(320)
            ->crop(true)
            ->thumbnail('https://github.com/ArthurHoaro');
echo '';
echo '';

// returns false
$wt->thumbnail('bad url');
```

Result:

> [![](https://cloud.githubusercontent.com/assets/1962678/19929568/37f6b796-a104-11e6-85fc-b039eb64bd97.png)](https://cloud.githubusercontent.com/assets/1962678/19929568/37f6b796-a104-11e6-85fc-b039eb64bd97.png)[![](https://cloud.githubusercontent.com/assets/1962678/19929823/a26fde9e-a105-11e6-915c-ce0db1ffe6b0.png)](https://cloud.githubusercontent.com/assets/1962678/19929823/a26fde9e-a105-11e6-915c-ce0db1ffe6b0.png)

Thumbnail configuration
-----------------------

[](#thumbnail-configuration)

There are 2 ways to set up thumbnail configuration:

- using `WebThumbnailer` helper functions as shown in *Usage* section.
- passing an array of settings to `thumbnail()` while getting a thumbnail. This will override any setting setup with the helper functions. Example:

```
$conf = [
    WebThumbnailer::MAX_HEIGHT => 320,
    WebThumbnailer::MAX_WIDTH => 320,
    WebThumbnailer::CROP => true
];
$wt->thumbnail('https://github.com/ArthurHoaro', $conf);
```

### Download mode

[](#download-mode)

There are 3 download modes, only one can be used at once:

- Download (default): it will download thumbnail, resize it and save it in the cache folder.
- Hotlink: it will use [image hotlinking](https://en.wikipedia.org/wiki/Inline_linking) if the domain authorize it, download it otherwise.
- Hotlink strict: it will use image hotlinking if the domain authorize it, fail otherwise.

Usage:

```
// Download (default value)
$wt = $wt->modeDownload();
$conf = [WebThumbnailer::DOWNLOAD];
// Hotlink
$wt = $wt->modeHotlink();
$conf = [WebThumbnailer::HOTLINK];
// Hotlink Strict
$wt = $wt->modeHotlinkStrict();
$conf = [WebThumbnailer::HOTLINK_STRICT];
```

> **Warning**: hotlinking means that thumbnails won't be resized, and have to be downloaded as their original size.

### Image Size

[](#image-size)

In download mode, thumbnails size can be defined using max width/height settings:

- with max height and max width, the thumbnail will be resized to match the first reached limit.
- with max height only, the thumbnail will be resized to the given height no matter its width.
- with max width only, the thumbnail will be resized to the given width no matter its height.
- if no size is provided, the default settings will apply (see Settings section).

Usage:

```
// Sizes are given in number of pixels as an integer
$wt = $wt->maxHeight(180);
$conf = [WebThumbnailer::MAX_HEIGHT => 180];
$wt = $wt->maxWidth(320);
$conf = [WebThumbnailer::MAX_WIDTH => 180];
```

> **Bonus feature**: for websites which support an open API regarding their thumbnail size (e.g. Imgur, FlickR), WebThumbnailer makes sure to download the smallest image matching size requirements.

### Image Crop

[](#image-crop)

Image resizing might not be enough, and thumbnails might have to have a fixed size. This option will crop the image (from its center) to match given dimensions.

> Note: max width AND height **must** be provided to use image crop.

Usage:

```
// Sizes are given in number of pixels as an integer
$wt = $wt->crop(true);
$conf = [WebThumbnailer::CROP => true];
```

### Resize Mode

[](#resize-mode)

This setting choose whether to use `imagecopyresized` (RESIZE mode) or `imagecopyresampled` (RESAMPLE mode):

- `RESAMPLE`: higher CPI usage, with better resized image rendering.
- `RESIZE`: faster and lower CPU usage, but the resized image might not look as good.

By default, this library uses `RESAMPLE` setting since the setting was introduced.

Example:

|---------------------RESIZE---------------------|---------------------RESAMPLE---------------------|

[![](https://user-images.githubusercontent.com/28786873/195634626-ec80e2ac-43f1-4f00-a507-8ba30dc5dda7.jpg)](https://user-images.githubusercontent.com/28786873/195634626-ec80e2ac-43f1-4f00-a507-8ba30dc5dda7.jpg)[![](https://user-images.githubusercontent.com/28786873/195634635-87f84476-e923-461c-accf-d3e5988e33a5.jpg)](https://user-images.githubusercontent.com/28786873/195634635-87f84476-e923-461c-accf-d3e5988e33a5.jpg)

Usage:

```
// Resize
$wt = $wt->resize();
$conf = [WebThumbnailer::RESIZE_MODE => WebThumbnailer::RESIZE];

// Resample
$wt = $wt->resample();
$conf = [WebThumbnailer::RESIZE_MODE => WebThumbnailer::RESAMPLE];
```

### Miscellaneous

[](#miscellaneous)

- **NOCACHE**: Force the thumbnail to be resolved and downloaded instead of using cache files.
- **DEBUG**: Will throw an exception if an error occurred or if no thumbnail is found, instead of returning `false`.
- **VERBOSE**: Will log an entry in error log if a thumbnail could not be retrieved.
- **DOWNLOAD\_TIMEOUT**: Override download timeout setting (in seconds).
- **DOWNLOAD\_MAX\_SIZE**: Override download max size setting (in bytes).

Usage:

```
$wt = $wt
    ->noCache(true)
    ->debug(true)
    ->verbose(true)
    ->downloadTimeout(30)
    ->downloadMaxSize(4194304)
;
$conf = [
    WebThumbnailer::NOCACHE => true,
    WebThumbnailer::DEBUG => true,
    WebThumbnailer::VERBOSE => true,
    WebThumbnailer::DOWNLOAD_TIMEOUT => 30,
    WebThumbnailer::DOWNLOAD_MAX_SIZE => 4194304,
];
```

Settings
--------

[](#settings)

Settings are stored in JSON, and can be overrode using a custom JSON file:

```
use WebThumbnailer\Application\ConfigManager;

ConfigManager::addFile('conf/mysettings.json');
```

Available settings:

- `default`:
    - `download_mode`: default download mode (`DOWNLOAD`, `HOTLINK` or `HOTLINK_STRICT`).
    - `timeout`: default download timeout, in seconds.
    - `max_img_dl`: default download max size, in bytes.
    - `max_width`: default max width if no size requirement is provided.
    - `max_height`: default max height if no size requirement is provided.
    - `cache_duration`: cache validity duration, in seconds (use a negative value for infinite cache).
- `path`:
    - `cache`: cache path.
- `apache_version`: force `.htaccess` syntax depending on Apache's version, otherwise it uses `mod_version`(allowed values: `2.2` or `2.4`).

Thumbnails path
---------------

[](#thumbnails-path)

In download mode, the path to the thumbnail returned by WebThumbnailer library will depend on what's provided to the `path.cache` setting. If an absolute path is set, thumbnails will be attached to an absolute path, same for relative.

Relative path will depend on the entry point of the execution. For example, if your entry point for all request is an `index.php` file in your project root directory, the default `cache/` setting will create a `cache/` folder in the root directory. Another example, for Symfony, the cache folder will be relative to the `web/` directory, which is the entry point with `app.php`.

If you don't have a single entry point in your project folder structure, you should provide an absolute path and process the path yourself.

Contributing
------------

[](#contributing)

WebThumbnailer can easily support more website by adding new rules in `rules.json` using one of the default Finders, or by writing a new Finder for specific cases.

Please report any issue you might encounter.

Also, feel free to correct any horrible English mistake I may have made in this README.

License
-------

[](#license)

MIT license, see LICENSE.md

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity37

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 99.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~102 days

Recently: every ~196 days

Total

19

Last Release

1271d ago

Major Versions

v1.3.1 → v2.0.02019-08-10

PHP version history (2 changes)v1.0.0PHP >=5.6

v2.0.0PHP >=7.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c10a2db899f8a62f26beb418c0ea969ae714921b8e39bef7145f046cacd18f9?d=identicon)[ArthurHoaro](/maintainers/ArthurHoaro)

---

Top Contributors

[![ArthurHoaro](https://avatars.githubusercontent.com/u/1962678?v=4)](https://github.com/ArthurHoaro "ArthurHoaro (129 commits)")[![jvalleroy](https://avatars.githubusercontent.com/u/178876?v=4)](https://github.com/jvalleroy "jvalleroy (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/arthurhoaro-web-thumbnailer/health.svg)

```
[![Health](https://phpackages.com/badges/arthurhoaro-web-thumbnailer/health.svg)](https://phpackages.com/packages/arthurhoaro-web-thumbnailer)
```

###  Alternatives

[milon/barcode

Barcode generator like Qr Code, PDF417, C39, C39+, C39E, C39E+, C93, S25, S25+, I25, I25+, C128, C128A, C128B, C128C, 2-Digits UPC-Based Extention, 5-Digits UPC-Based Extention, EAN 8, EAN 13, UPC-A, UPC-E, MSI (Variation of Plessey code)

1.5k13.3M39](/packages/milon-barcode)[bkwld/croppa

Image thumbnail creation through specially formatted URLs for Laravel

510496.0k23](/packages/bkwld-croppa)[goat1000/svggraph

Generates SVG graphs

132849.6k3](/packages/goat1000-svggraph)[cohensive/embed

Media Embed (for Laravel or as a standalone).

120370.4k](/packages/cohensive-embed)[netresearch/rte-ckeditor-image

Image support in CKEditor for the TYPO3 ecosystem - by Netresearch

63991.3k4](/packages/netresearch-rte-ckeditor-image)[humanmade/tachyon-plugin

Rewrites WordPress image URLs to use Tachyon

87338.5k2](/packages/humanmade-tachyon-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)