tfd/statamic-cloudinary

v1.4.1 2024-11-08 11:05 UTC

Requires

• statamic/cms: ^3.1 || ^4.0 || ^5.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2
• phpunit/phpunit: ^9.3
• squizlabs/php_codesniffer: ^3.6

MIT

README

Cloudinary is a Statamic addon that allows you to use cloudinary to deliver your assets.

Features

This addon allows you to:

• leverage the transformation and delivery power of cloudinary
• usable with images and videos
• automatically upload media to cloudinary

How to Install

Run the following command from your project root:

composer require tfd/statamic-cloudinary

How to Use

1. Create a Cloudinary Account

Go to https://cloudinary.com and create a free account.
It is recommended to create a new folder inside cloudinary's Media Library that hosts all the media of your website.

Go to Settings > Upload > Auto upload mapping and fill out

• Folder: Your newly create folder
• URL prefix: Your website's URL, including a trailing slash

Grab the following information from your cloudinary Dashboard:

• Cloud name
• API Environment variable

2. Publish the cloudinary configuration file

Run the following command from your project root:

php artisan vendor:publish --tag="cloudinary-config"

This will create a cloudinary.php file inside config/statamic.

3. Setup cloudinary variables

Enter at least the following data in the cloudinary.php file or use your project's .env file.
The auto_mapping_folder is the folder you've created during the first step. The url is the API Environment variable you've copied from the first step.

<?php

return [
    'cloud_name' => env('CLOUDINARY_CLOUD_NAME', null),
    'auto_mapping_folder' => env('CLOUDINARY_AUTO_MAPPING_FOLDER', ''),
    'url' => env('CLOUDINARY_URL', ''),
];

CLOUDINARY_CLOUD_NAME=xxx
CLOUDINARY_AUTO_MAPPING_FOLDER=xxx
CLOUDINARY_URL=cloudinary://xxx:xxx@xxx

3.1. Using an External URL

If your assets are served through an external URL, you need to set an additional configuration option, either in the cloudinary.php config file:

<?php

return [
  // ...
  'external_url_prefix' => env('CLOUDINARY_EXTERNAL_URL_PREFIX', 'https://my-external-asset-url.com'),
];

... or in the .env file:

CLOUDINARY_EXTERNAL_URL_PREFIX=https://my-external-asset-url.com

For example, if you are using DigitalOcean Spaces storage and your assets are served from this URL:
https://my-project.us1.digitaloceanspaces.com/website/image.jpg, the external URL consists of two parts:

• https://my-project.us1.digitaloceanspaces.com - The DigitalOcean base URL
• /website - The root folder in DigitalOcean

The actual value you need to set in the config or .env file would be:
CLOUDINARY_EXTERNAL_URL_PREFIX=https://my-project.us1.digitaloceanspaces.com/website/

4. Use the cloudinary tag

You are now ready to use the cloudinary tag inside your views.

Some examples

<img src="{{ cloudinary:image }}" />

The image is transformed according to the default transformation parameters, see step 5.

<img src="{{ cloudinary:image width="800" height="500" }}">

The image is resized to 800 x 500 px.

{{ cloudinary:image width="400" height="300" }}
<img src="{{ url }}" width="{{ width }}" height="{{ height }}" />
{{ /cloudinary:image }}

Alternative usage with tag pairs.

{{ cloudinary:image width="400" }}
<img src="{{ url }}" width="{{ width }}" height="{{ height }}" />
{{ /cloudinary:image }}

If you only provide width or height when using the tag pair, the addon automatically calculates the other dimension depending on the image's aspect ratio and makes this value available in your view.

<video src="{{ cloudinary:video width="600" height="400" effect="blur:1000" }}" muted autoplay></video>

Videos are also supported. Depending on the video size the initial (automatic) upload to cloudinary might take some time.

<img src="{{ cloudinary:image width="800" height="500" quality="10"
effect="blur:800" opacity="20" }}" alt="">

Usage with other parameters.

<x-cloudinary-image
  :src="$featured_image"
  height="422"
  alt="Das ist ein Test"
  effect="sepia:80"
/>

There is also a custom blade component to use cloudinary in your blade templates. The src attribute is required.

5. Available parameters

For more information about these parameters, head over to the cloudinary documentation.

6. Adjust default parameters

You can adjust the default parameters to your likings in the config/statamic/cloudinary.php configuration file:

return [
  'default_transformations' => [
    'image' => [
      'crop' => 'fill',
      'dpr' => 'auto',
      'fetch_format' => 'auto',
      'gravity' => 'auto',
      'quality' => 'auto',
    ],
    'video' => [
      'crop' => 'fill',
      'dpr' => 'auto',
      'fetch_format' => 'auto',
      'quality' => 'auto',
    ],
  ],
];

7. Publish the cloudinary views

Run the following command from your project root:

php artisan vendor:publish --tag="cloudinary-views"

This will publish the cloudinary views to the resources/views/vendor/cloudinaryfolder.