A BlurHash implementation for Craft CMS.

Related tags

CMS craft-blurhash
Overview

BlurHash plugin for Craft CMS 3.x

Buy us a tree

Render a BlurHash from a given asset in Craft CMS.

A BlurHash is a compact representation of a placeholder for an image. A blurred version of an image, useful for displaying whilst the full resolution image is loading.

This plugin uses kornrunner's PHP implementation of BlurHash, php-blurhash.

Requirements

  • Craft CMD 3.x
  • PHP 7.3 or higher
  • GD / ImageMagick (as required by Craft CMS)

Installation

Install the plugin as follows:

  1. Open your terminal and go to your Craft project:

     cd /path/to/project
    
  2. Then tell Composer to load the plugin:

     composer require dodecastudio/craft-blurhash
    
  3. In the Control Panel, go to Settings → Plugins and click the “Install” button for BlurHash.

BlurHash Overview

The BlurHash plugin will generate a BlurHash image from a craft asset. Here's an example of what you can expect:

Input:

Result:

Using BlurHash

Common use

To use the plugin, first grab an asset from Craft, perhaps something like this:

{% set testAsset = craft.assets().id(101).one() %}

You can then pass your asset to the plugin's blurhash function, which will return a blurhash image as a data-url, perfect for using in an img element like so:

<img src="{{ blurhash(testAsset) }}" width="{{testAsset.width}}" height="{{testAsset.height}}" />

Other features

Generating a blurhash string

If you just want to generate just a blurhash string from a given asset, you can use the blurhash filter like this:

{{ testAsset|blurhash }}

Which will return something like this:

twigK-I#.3ofof_4ofj[%Mayay

You might want to store this in some way, for use later.

Generating a blurhash image from a blurhash string

If you already have a blurhash string and want to generate an image from it, you can use the blurhashToUri function like this:

<img src="{{ blurhashToUri('K-I#.3ofof_4ofj[%Mayay') }}" width="256" height="256" alt="Blurhash image" />

Licence 🌳

This package is Treeware. If you use it in production, then we ask that you buy the world a tree. And why wouldn't you? By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Comments
  • Craft 4 beta, GQL:

    Craft 4 beta, GQL: "Malformed UTF-8 characters, possibly incorrectly encoded"

    I'm running Craft 4 beta and querying via GraphQL.

    My assets are in as S3 volume. I also have Imager-X installed, which is set up to use Imgix.

    When trying to select blurhashUri: url @assetToBlurHash on an asset, I am getting this:

    {
      "error": "Malformed UTF-8 characters, possibly incorrectly encoded",
      "exception": "yii\\base\\InvalidArgumentException",
      "file": "/srv/my-project/vendor/yiisoft/yii2/helpers/BaseJson.php",
      "line": 147,
      "trace": [
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/helpers/BaseJson.php",
          "line": 88,
          "function": "handleJsonError",
          "class": "yii\\helpers\\BaseJson",
          "type": "::"
        },
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/web/JsonResponseFormatter.php",
          "line": 133,
          "function": "encode",
          "class": "yii\\helpers\\BaseJson",
          "type": "::"
        },
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/web/JsonResponseFormatter.php",
          "line": 112,
          "function": "formatJson",
          "class": "yii\\web\\JsonResponseFormatter",
          "type": "->"
        },
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/web/Response.php",
          "line": 1095,
          "function": "format",
          "class": "yii\\web\\JsonResponseFormatter",
          "type": "->"
        },
        {
          "file": "/srv/my-project/vendor/craftcms/cms/src/web/Response.php",
          "line": 275,
          "function": "prepare",
          "class": "yii\\web\\Response",
          "type": "->"
        },
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/web/Response.php",
          "line": 339,
          "function": "prepare",
          "class": "craft\\web\\Response",
          "type": "->"
        },
        {
          "file": "/srv/my-project/vendor/yiisoft/yii2/base/Application.php",
          "line": 390,
          "function": "send",
          "class": "yii\\web\\Response",
          "type": "->"
        },
        {
          "file": "/srv/my-project/web/index.php",
          "line": 12,
          "function": "run",
          "class": "yii\\base\\Application",
          "type": "->"
        }
      ]
    }
    

    I have the same error if I pass (asUri: false).

    Side question: are the results cached anywhere? Or is the full-size image going to be pulled from S3 and reprocessed every time I query for the blurhash of a specific asset?

    opened by tremby 21
  • blurhash size / aspect ratio

    blurhash size / aspect ratio

    Hi, is it possible to set the size, the blur hash should have? All the blur hashes I generate are 64x64px big. I need to keep the original aspect ratio of the image.

    enhancement good first issue 
    opened by olsp 8
  • Add a file exists check to prevent crash

    Add a file exists check to prevent crash

    Hi,

    Loving the plugin, but I was wondering if it would it be possible to add a file exists check to BlurHash functions to prevent errors like the following if a file doesn't exist locally?

    Screen Shot 2022-04-13 at 2 04 32 pm

    We want to use BlurHash along with Untransform so we can use images from our staging site instead of having to download them all the time

    Thanks!

    bug 
    opened by mokopan 7
  • @assetToBlurHash fails when using a dev server on plain HTTP trying to retrieve an asset over HTTPS to generate a BlurHash

    @assetToBlurHash fails when using a dev server on plain HTTP trying to retrieve an asset over HTTPS to generate a BlurHash

    Your plugin is great! Only a small problem, when I'm trying to use it on a local Craft Nitro dev environment that is running over plain HTTP, the blurHash fails with an empty string, probably related to an SSL connect error when trying to grab assets over HTTPS.

    If you are using cURL behind the scenes, you might just need to add an -k/--insecure flag which would allow retrieving the assets.

    This way local dev environments will have the same functionality as proper Staging or Prod environments over HTTPS.

    opened by HalCodes 4
  • Version 2.0.2 seems to break GraphQL

    Version 2.0.2 seems to break GraphQL

    After updating to 2.0.2 my GraphQL query doesn't work any longer. I get the following error: dodecastudio\\blurhash\\qgl\\directives\\AssetToBlurHash::apply(): Return value must be of type string, null returned"

    After downgrading to 2.0.1, it works again.

    In the query, I use blurhashUri: url @assetToBlurHash

    opened by olsp 2
  • Bump twig/twig from 2.14.8 to 2.14.11

    Bump twig/twig from 2.14.8 to 2.14.11

    Bumps twig/twig from 2.14.8 to 2.14.11.

    Changelog

    Sourced from twig/twig's changelog.

    2.14.11 (2022-02-04)

    • Fix a security issue when in a sandbox: the sort filter must require a Closure for the arrow parameter

    2.14.10 (2022-01-03)

    • Allow more null arguments when Twig expects a string (for better 8.1 support)

    2.14.9 (2022-01-03)

    • Allow null when Twig expects a string (for better 8.1 support)
    • Add support for PHP 7.1 back
    • Make some performance optimizations
    • Allow Symfony translation contract v3+
    Commits
    • 66baa66 Prepare the 2.14.11 release
    • 22b9dc3 bug #3641 Disallow non closures in sort filter when the sanbox mode is enab...
    • 2eb3308 Disallow non closures in sort filter when the sanbox mode is enabled
    • e056e63 bug #3638 Fix call to deprecated "convertToHtml" method (jderusse)
    • 779fdd0 Fix call to deprecated "convertToHtml" method
    • bbc3377 minor #3629 Fix map example output (alexander-schranz)
    • 9741173 Fix map example output
    • 9984a6e minor #3628 Rename variables used in map method (alexander-schranz)
    • b74cf2a Rename variables used in map method
    • e8068a9 bug #3626 The deprecated null value for the method round has been changed to ...
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 1
  • 1.2.3 updates

    1.2.3 updates

    • Adds file checking to prevent errors if a file has been removed from disk but not from Craft DB (Thanks to @mokopan for the suggestion 🙌).
    • Adds a helper function, memoryInfo. This will return the approximate memory required (in bytes) to load an asset in to memory. Available as a twig filter and in GraphQL.
    • Added a sample GraphQL asset query, located in resources/demo.graphql.
    opened by tomkiss 0
  • @assetToBlurHash won't generate from transformed asset

    @assetToBlurHash won't generate from transformed asset

    First off, your plugin works great! I am trying to get a blurred hash from a transformed asset in GraphQL.

    I've try this GraphQL query (modified from your demo.graphql, but it keeps generating the original asset dimensions instead of the transformed one (squared)

    query assetQuery {
      asset(id: 1) {
        urlWithParams: url(width: 100, height:100) @assetToBlurHash
        urlWithDirective: url @transform(width: 100, height:100) @assetToBlurHash
      }
    }
    

    Thoughts?

    enhancement 
    opened by webrgp 1
Releases(v2.0.4)
  • v2.0.4(Aug 18, 2022)

  • v2.0.3(Jun 20, 2022)

    • Updated: Added more filetypes to the supported filetypes list (was being a little overly cautious previously).
    • Fixed: Incorrect variable value being returned by Graph QL query, fixes #15.
    Source code(tar.gz)
    Source code(zip)
  • v2.0.2(Jun 16, 2022)

    • Updated: Composer.json file to better support Craft 3 and 4 across a single version. Older branches are now archives, and will be removed in the future.
    Source code(tar.gz)
    Source code(zip)
  • v1.2.5(May 20, 2022)

  • v2.0.1(May 16, 2022)

  • v2.0.0-beta3(Apr 19, 2022)

    • Adds file checking to prevent errors if a file has been removed from disk but not from Craft DB (Thanks to @mokopan for the suggestion 🙌).
    • Adds a helper function, memoryInfo. This will return the approximate memory required (in bytes) to load an asset in to memory. Available as a twig filter and in GraphQL.
    • Added a sample GraphQL asset query, located in resources/demo.graphql.
    Source code(tar.gz)
    Source code(zip)
  • v1.2.4(Apr 19, 2022)

  • v1.2.3(Apr 16, 2022)

    • Adds file checking to prevent errors if a file has been removed from disk but not from Craft DB (Thanks to @mokopan for the suggestion 🙌).
    • Adds a helper function, memoryInfo. This will return the approximate memory required (in bytes) to load an asset in to memory. Available as a twig filter and in GraphQL.
    • Added a sample GraphQL asset query, located in resources/demo.graphql.
    Source code(tar.gz)
    Source code(zip)
  • v2.0.0-beta.2(Mar 23, 2022)

    • Ensures blurhash images are to the same aspect ratio as the original Craft Asset.
    • A demo template has been added, copy it to your Craft CMS project to get started. Find it in resources/demo.twig.
    Source code(tar.gz)
    Source code(zip)
  • v1.2.2(Mar 23, 2022)

    • Ensures blurhash images are to the same aspect ratio as the original Craft Asset.
    • A demo template has been added, copy it to your Craft CMS project to get started. Find it in resources/demo.twig.
    Source code(tar.gz)
    Source code(zip)
  • v2.0.0-beta.1(Mar 10, 2022)

  • v1.2.1(Mar 10, 2022)

  • v1.1.1(Nov 29, 2021)

  • v1.1.0(Nov 29, 2021)

  • v1.0.4(Aug 20, 2021)

  • v1.0.3(Aug 5, 2021)

  • v1.0.2(Aug 5, 2021)

  • v1.0.1(Aug 3, 2021)

  • v1.0.0(Aug 3, 2021)

Owner
Dodeca Studio
A creative studio specialising in web design.
Dodeca Studio
Craft is a flexible, user-friendly CMS for creating custom digital experiences on the web and beyond.

About Craft CMS Craft is a flexible, user-friendly CMS for creating custom digital experiences on the web and beyond. It features: An intuitive, user-

Craft CMS 2.9k Jan 1, 2023
Allows the use of the Vite.js next generation frontend tooling with Craft CMS

Vite plugin for Craft CMS 3.x Allows the use of the Vite.js next generation frontend tooling with Craft CMS Related Article: Vite.js Next Generation F

nystudio107 38 Dec 30, 2022
Plugin Vite is the conduit between Craft CMS plugins and Vite, with manifest.json & HMR support

Plugin Vite Related Articles: Vite.js Next Generation Frontend Tooling + Craft CMS A Vite Buildchain for Craft CMS Plugins Requirements Craft CMS 3.0.

nystudio107 8 Dec 30, 2022
Plugin for Craft CMS that makes it easy to interact with the Instagram Basic Display API and Instagram oEmbed.

Instagram Basic Display plugin for Craft CMS 3.x This plugin creates endpoints in your Craft install for you to consume the Instagram Basic Display AP

Jonathan Melville 5 Dec 20, 2022
Provides autocompletion for Craft CMS and plugins in Twig templates.

Autocomplete for Craft CMS Provides autocompletion for Craft CMS and plugins in Twig templates. Currently works with PhpStorm only, as VSCode does not

PutYourLightsOn 12 Nov 23, 2021
Provides Twig template IDE autocomplete of Craft CMS & plugin variables

Autocomplete for Craft CMS 3.x Provides Twig template IDE autocompletion for Craft CMS and plugin/module variables and element types. Works with PhpSt

nystudio107 35 Dec 21, 2022
Edit richt text content in Craft CMS using Article by Imperavi.

Article Editor About the plugin This plugin brings the powerful Article Editor from Imperavi to Craft CMS, allowing you to make create beautiful rich

Creativeorange 6 Mar 30, 2022
A plugin for Craft CMS 3.X that allows for GraphQL search functionality for matching on fields of nested entries.

Nested Entry GraphQL Plugin This Craft CMS plugin allows for performing graphQL search queries that match on fields on nested entries-as-a-field. What

Rubin EPO 2 Sep 10, 2021
Element Relations Plugin for Craft CMS 3.x

Element Relations Plugin for Craft CMS 3.x This plugin shows all relations of an element. For example, where an asset, entry or any other element is l

Frederic Köberl 2 Jul 18, 2022
Monet Plugin for Craft CMS

A Monet field can be added to asset elements which will generate and store an efficient placeholder image to be displayed inline, whilst the full asset is loading.

Chris Dyer 1 Jan 21, 2022
Provides a twig editor field with Twig & Craft API autocomplete

Twigfield for Craft CMS 3.x & 4.x Provides a twig editor field with Twig & Craft API autocomplete Requirements Twigfield requires Craft CMS 3.0 or 4.0

nystudio107 13 Nov 1, 2022
Flextype is an open-source Hybrid Content Management System with the freedom of a headless CMS and with the full functionality of a traditional CMS

Flextype is an open-source Hybrid Content Management System with the freedom of a headless CMS and with the full functionality of a traditional CMS. Building this Content Management System, we focused on simplicity. To achieve this, we implemented a simple but powerful API's.

Flextype 524 Dec 30, 2022
PHPVibe Open source video CMS / Video Sharing CMS / Youtube Api v3 / Video Embeds

PHPVibe Video CMS Free Video Sharing CMS The modern choice of design inspired by Youtube and a social videos sharing module that may just cut it for y

MediaVibe 71 Dec 18, 2022
NukeViet 132 Nov 27, 2022
BaiCloud-cms is a powerful open source CMS that allows you to create professional websites and scalable web applications. Visit the project website for more information.

BaiCloud-cms About BaiCloud-cms is a powerful open source CMS that allows you to create professional websites and scalable web applications. Visit the

null 5 Aug 15, 2022
Baicloud CMS is a lightweight content management system (CMS) based on PHP and MySQL and running on Linux, windows and other platforms

BaiCloud-cms About BaiCloud-cms is a powerful open source CMS that allows you to create professional websites and scalable web applications. Visit the

null 5 Aug 15, 2022
Doptor CMS is a Laravel 5 based CMS

Introduction Doptor CMS is a Laravel 5 based CMS. Find out more about Doptor by reading below. ;) About Doptor CMS Doptor is an Integrated and well-de

DOPTOR 4 Sep 11, 2022
Bismuth CMS is a ready-made Website CMS based on Yii 2 Advance Template

Bismuth CMS is a ready-made Website CMS based on Yii 2 Advance Template, it's the simplest and easy to set up CMS you may come across.

Hamadas Telebrain 1 Feb 11, 2022
Bootstrap CMS - PHP CMS powered by Laravel 5 and Sentry

Bootstrap CMS Bootstrap CMS was created by, and is maintained by Graham Campbell, and is a PHP CMS powered by Laravel 5.1 and Sentry. It utilises many

Bootstrap CMS 2.5k Dec 27, 2022