- How do I install iamriajul/thumbhash-laravel in a Laravel app?
- Install it with Composer using composer require iamriajul/thumbhash-laravel. The package is a thin service-provider wrapper, so Laravel's package auto-discovery registers it without manual provider edits. You should also publish any provided config file with the vendor:publish command if you need to tweak defaults. It assumes you already have an image driver available, since decoding is delegated to Intervention Image.
- Which Laravel and PHP versions does thumbhash-laravel support?
- The package targets PHP 8.x and modern Laravel releases that support package auto-discovery. Because the 1.0.3 patch fixes a float conversion warning tied to stricter PHP float-to-int handling and Intervention Image, you should confirm the exact constraints in the package's composer.json before adopting. Check that your app's PHP minor version and deprecation settings match what the package CI exercises.
- How do I generate a ThumbHash from an uploaded image?
- Decode the image to raw RGBA pixel data with Intervention Image, then pass that data to the package's facade or helper to get back a roughly 25-byte ThumbHash string. Store that short string in a nullable string column on your model, typically alongside the image path. Generation is deterministic for identical pixel input, so you can safely regenerate and compare hashes in tests.
- How do I render a ThumbHash placeholder in Blade while the full image loads?
- The package turns a stored hash back into a small placeholder, either as a data URI or as an inline SVG or canvas payload, which you can drop into a Blade partial as the image background or src. Pair it with the real image's known aspect ratio so the container reserves space and layout shift stays minimal. A common pattern is a blurred placeholder layer that is swapped or covered once the full-size image loads.
- Should I generate ThumbHashes synchronously in the request or in a queued job?
- Hashing is cheap relative to full thumbnail generation, but decoding the source image is the expensive part, so for large uploads a queued job is usually the safer choice. Many teams hash inside the same job that already produces resized variants, keeping the upload request fast. Confirm whether your version ships a ShouldQueue-friendly path or whether you should call the hasher from your own job class.
- Which image formats can I hash with this package?
- ThumbHash needs decoded RGBA pixel data, so anything your Intervention driver can decode to that form generally works, including common JPEG, PNG, and WebP inputs. Animated GIFs, HEIC/HEIF, CMYK JPEGs, and SVG files are either unsupported or handled inconsistently by the underlying driver. Validate and normalize uploads before hashing, and document behavior for oversized images and memory limits.
- Does thumbhash-laravel work with Intervention Image 2.x and 3.x?
- This is the main compatibility axis to verify: Intervention Image 3.x was a breaking rewrite of the driver architecture, so support for 2.x and 3.x may differ. Check the composer.json constraints rather than assuming, and note which driver (GD or Imagick) your app uses. The 1.0.3 float conversion fix touches exactly this boundary, so test on the major version you actually pin.
- Why did my placeholders change appearance after a routine composer update?
- ThumbHash output is deterministic given identical RGBA input, but the decoder produces that input, so a new Intervention Image or GD/Imagick version can alter resampling, EXIF orientation, or color profile handling. That changes the hash without any change to this package. Pin your image stack, and run a fixture test that hashes a known image set before and after upgrading to prove output is stable.
- How do I backfill the hash column for images that already exist?
- Make the hash column nullable so legacy rows and rows where hashing failed do not break queries, then backfill with a queued job or an artisan command that iterates existing records. Hash in chunks to keep memory bounded, since each record requires decoding the original file. A one-time fixture test against your 1.0.3 upgrade is also worth running to confirm the fix is behavior-neutral rather than a truncating cast.
- Is iamriajul/thumbhash-laravel safe to depend on in production?
- It is a small, narrow package maintained primarily by a single author at a pre-2.0 version, so treat bus factor as a real consideration rather than a footnote. The upside is that the code surface is tiny, so forking or vendoring it is a realistic fallback if maintenance stalls. The bigger risk sits in transitive coupling to Intervention Image, not in the hashing logic itself. If you already generate thumbnails with Intervention, the marginal dependency cost is close to zero.