README

A collection of utilities I use in Statamic projects.

Installation

Install the package via composer:

composer require daun/statamic-utils

Registration

Modifiers, Tags, Scopes, etc. need to be registered in your app's service provider.

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        \Daun\StatamicUtils\Modifiers\ToIterable::register();
        \Daun\StatamicUtils\Scopes\Image::register();
    }
}

Modifiers

Asset

Return or find an asset by id or url.

{{# Fetch asset if url was passed #}}
{{ image = image | asset }}

Asset Meta

Get an asset's meta value by key, iterating over possible locales. Falls back to the unsuffixed key if no localized value is found. Array values are rendered as Bard HTML.

{{ caption = asset | asset_meta('caption') }}

Pass an explicit locale as the optional second parameter to prioritize it over the current locale.

{{ caption = asset | asset_meta('caption', 'de') }}

Br 2 Nl

Strip tags, but keep line breaks as visually intended by the html.

<p>{{ rich_text | br2nl }}</p>

Count Safe

Count the number of items in an array or iterable. Returns 0 for null values and 1 for non-iterable values.

{{ if locations | count_safe }} ... {{ /if }}

Except

Remove keys from an array or collection.

{{ params = get | except('page', 'q') }}

Hostname

Extract the hostname from a URL, stripping a leading www.. Non-URL values return null.

{{ 'https://www.example.com/path' | hostname }} {{# example.com #}}

Is Current

Check if the current page matches the given URL. Pass true to also include ancestors in the comparison.

{{ if url | is_current }}
    aria-current="page"
{{ elseif url | is_current(true) }}
    aria-current="true"
{{ /if }}

Max

Return the highest value in an array or collection.

{{ large = sizes | max }}

Min

Return the lowest value in an array or collection.

{{ small = sizes | min }}

Nl 2 Str

Replace newlines with a specified string.

<p>{{ rich_text | nl2str(', ') }}</p>

Orientation

Determine the orientation of an aspect ratio value. Returns portrait, landscape, or square.

{{ orientation = asset:ratio | orientation }}

A ratio is considered square if it is within 5% of 1:1. Use the optional first parameter to specify a custom threshold, e.g. 1.25 for a 25% tolerance or 1.0 for a strict 1:1 ratio.

{{ orientation = image | orientation(1.25) }}

P 2 Br

Convert paragraph tags to line breaks.

<p>{{ rich_text | p2br }}</p>

Push

Push an item onto an array or collection.

{{ items = (items | push:{newitem}) }}

Qr Code

Return a QR code image URL (SVG) for a given URL or phone number, generated via quickchart.io.

<img src="{{ url | qr_code }}" alt="QR code">

Query Append

Append a query string to a URL, using ? or & as appropriate depending on whether the URL already contains a query string.

{{ url | query_append('utm_source=newsletter') }}

Resolve

Resolves unfetched query builder queries to their results. Useful when passing around entries field values in combination with nocache tags to avoid serialization issues.

{{ partial:partials/data-table :rows="news | resolve" }}

Standard Ratio

Map an aspect ratio value to its closest equivalent in a predefined set of standard ratios.

{{ ratio = asset:ratio | standard_ratio }}

Default ratios are 1:1, 4:3, 3:2, 16:9 and their inverses. You can globally define custom ratios:

\Daun\StatamicUtils\Modifiers\StandardRatio::define(['5/4', '4/5']);

To Int

Convert a value to an integer. Special case: converts a mixed array to an array of integers.

{{ number_array = mixed_array | to_int }}

To Float

Convert a value to a float. Special case: converts a mixed array to an array of floats.

{{ number_array = mixed_array | to_float }}

To Iterable

Wrap a value in an array if it is not already iterable.

Locations: {{ (locations ?? location) | to_iterable | pluck('title') | list }}

Wrap Words

Wrap each word in a <span> tag. Use the optional first parameter to specify a different wrapper tag.

<p>{{ title | wrap_words }}</p>
<ul>
  {{ title | wrap_words('li') }}
</ul>

Actions

Edit Collection Mount

Redirect to the edit form of a collection's mount page from its entry listing view.

Show Mount Entries

Redirect to the entry listing view of a collection's mount page from its entry edit view.

Query Scopes

Apply query scopes to narrow down query results.

Published: Filter out unpublished entries
Image: Filter assets that are images (pixel + vector)
ImagePixel: Filter assets that are pixel images (jpeg, png, gif, etc)
ImageVector: Filter assets that are vector images (svg)
ImageOrVideo: Filter assets that are images or videos
Video: Filter assets that are video files
Audio: Filter assets that are audio files

Search Filters

Classes for filtering entries for search indexing.

Published: Filter out unpublished entries.
All: Include all entries, regardless of their published status.

return [
    'indexes' => [
        'articles' => [
            'searchables' => 'collection:articles',
            'filter' => \Daun\StatamicUtils\Search\Filters\Published::class,
        ]
    ]
];

Search Transformers

Classes for transforming fields for search indexing.

BardText: Extract plain text from a Bard field.
RelationshipTitle: Return an array of titles of all relationships (entries, terms, etc)
RelationshipTitleLocalizations: Return an array of relationship titles in all languages

return [
    'indexes' => [
        'articles' => [
            'searchables' => 'collection:articles',
            'transformers' => [
                'content' => \Daun\StatamicUtils\Search\Transformers\BardText::class,
                'categories' => \Daun\StatamicUtils\Search\Transformers\RelationshipTitle::class,
            ]
        ]
    ]
];

Forms

SendRateLimitedEmail

A job that sends form submission emails with a rate limit of 1 per second. It extends/wraps the default SendEmail job and can be used as a drop-in replacement with otherwise identical behavior.

// config/statamic/forms.php
return [
    'send_email_job' => \Daun\StatamicUtils\Forms\SendRateLimitedEmail::class,
];

Cache

Query Params

Get an up-to-date list of marketing query params to ignore when caching a page.

// config/statamic/static_caching.php

return [
    'disallowed_query_strings' => \Daun\StatamicUtils\Cache\QueryParams::toIgnore()
];

Utilities

Data Resolution

The Resolver class provides a way of resolving wrapped data to their actual underlying values. This is useful for value objects, query builders, fluent tags, etc.

use Daun\StatamicUtils\Data\Resolver;

$value = /* query builder, wrapped in value object */;
$actual = Resolver::actual($value);

Control Panel

Translations

Ensure the existence of customized Create Entry buttons for all data types. Throws an exception if a collection or taxonomy is missing the required translation key.

\Daun\StatamicUtils\ControlPanel\Translations::ensureCreateButtonLabels();

License

MIT

daun / statamic-utils

Maintainers

Package info

Statistics

Security