- How do I install srwiez/thumbhash in a Laravel application?
- Install it with Composer by running composer require srwiez/thumbhash from your project root. Because it is a leaf library with no service provider and no framework coupling, there is nothing to register in config/app.php. You can call it directly from a controller, a queued job, an observer, or a small service class of your own. Run composer dump-autoload afterwards if you use an optimized autoloader in production.
- Does srwiez/thumbhash need GD or Imagick to encode an image?
- Encoding has to read source pixels, so the practical requirement is whichever extension decodes your uploaded files, typically GD or Imagick. Decoding a hash back into a blurred preview is pure PHP and needs no image extension at all. Before rolling it out, check the package composer.json and README for the exact extension constraint and confirm it matches your worker runtime. If your upload workers already run Intervention Image, you almost certainly have what you need.
- Which PHP and Laravel versions does srwiez/thumbhash support?
- The library is framework-agnostic, so it fits Laravel 10, 11 and 12 on PHP 8.1 and above without conflicting with the rest of your dependency tree. Confirm the exact php constraint in the package composer.json before pinning a version in production. Since there is no Laravel-specific code, framework upgrades will not break it. Check Packagist for the actual tagged release rather than trusting secondary listings.
- How should I store a ThumbHash in the database and render it in Blade?
- A ThumbHash is only about 20 to 35 bytes, so a nullable binary or short string column on your media table is enough, or you can cache it alongside the object key. Decode it to a base64 data URI through an accessor and render that URI as a CSS background layer behind the real image. A small Blade component such as x-thumbhash keeps the markup tidy and works the same way under Livewire. Storing the hash in the database lets you fetch placeholders in a single indexed query instead of a storage round-trip.
- What is the difference between ThumbHash and BlurHash?
- Both encode a tiny blurred preview, but ThumbHash also packs in aspect ratio and an optional alpha channel, so you can size the placeholder container correctly before the real image loads. That reduces layout shift rather than just showing a colored blur. ThumbHash payloads are typically 20 to 35 bytes, similar to or smaller than BlurHash strings. If you already use BlurHash, the alpha and aspect-ratio metadata are the main reasons to switch.
- Can I decode a ThumbHash to a data URI in PHP without GD or Imagick?
- Decoding is implemented in pure PHP, so you can turn a stored hash into an RGBA pixel buffer or a base64 data URI on any runtime, including inside a normal request cycle. That said, producing a data URI for a large placeholder size costs CPU proportional to the output dimensions. Keep the decode dimensions small, since the result is blurred anyway, and cache the resulting URI where you can. On high-traffic pages, decoding once at write time is usually cheaper than decoding on every render.
- Is encoding a ThumbHash from a large upload slow or memory heavy?
- The hashing step itself is trivial, but the expensive part is decoding a multi-megapixel JPEG or PNG into raw pixels first. On large uploads that decode can spike memory, so run it in a queued job with an explicit memory limit instead of in the upload request. Downscaling the image before hashing is the single biggest win, since a ThumbHash gains nothing from full resolution. Also feed it re-encoded, validated images rather than raw client files.
- How do I verify my PHP ThumbHash output matches the JavaScript reference implementation?
- ThumbHash is a third-party spec with implementations in JavaScript, Dart and Rust, so drift in alpha handling, color space or aspect-ratio rounding is possible. Build a golden-fixture test: encode a handful of known images in PHP, then decode those same hashes with the reference JavaScript decoder and compare the rendered output. Include one image with transparency and one non-square image to exercise the metadata paths. Run this in CI so a dependency bump cannot silently change how your placeholders render.
- Can I use srwiez/thumbhash in a queued job, Livewire, or Inertia?
- Yes. The package has no framework coupling, no service container bindings and no global state, so it is safe to call from a queued listener on an ImageUploaded event, an observer, or a plain service class. Because the output is just a string, passing the base64 data URI as an Inertia prop or binding it in a Blade component is straightforward. The recommended pattern is to encode once after upload, store the hash, and render it wherever needed.
- Is srwiez/thumbhash actively maintained and safe to depend on in production?
- It is a small MIT-licensed library with a modest star count and a single-maintainer profile, so plan for bus-factor risk even though the license lets you fork or vendor it. Pin an exact version, review the tagged release on Packagist, and check the issue tracker before upgrading. Because the code is pure PHP with a tiny API surface, wrapping it in your own service class makes it easy to swap out later. Treat any image-parsing dependency as part of your attack surface and only hash files you have already validated.