Laravel Blade Filters

Originated from conedevelopment/blade-filters, but with lots of improvements, the original doesn't support named arguments and filter context, which are essential in my case. this library implements a lexer and parser to analyze filter syntax.

Because this library is almost refactored and rewritten, this package renamed as videni/blade-filters, but the namespace still keeps it is.

• Laravel Blade Filters
  • Installation
  • Using the filters
    • Regular usage:
    • Named filter arguments
    • Chained usage:
    • Passing non-static values:
    • Passing variables as filter parameters:
    • Built-in Laravel functionality:
    • Limitations
      • Echos
      • Bitwise operators
  • The Filters
    • About the filters
    • The available filters
      • Currency
      • Date
      • Lcfirst
      • Reverse
      • Substr
      • Trim
      • Ucfirst
    • Supported built-in Str functions
  • Custom filter
    • Add simple custom filter
    • Filter provider
  • Testing

Installation

composer require "videni/blade-filters": "^1.0"

Using the filters

You can use the filters in any of your blade templates.

Regular usage:

{{ 'john' | ucfirst }} // John

Named filter arguments

{{ 'a wonderful place' | slug:separator='_', language='en' }}

For slug filter which provided by \Illuminate\Support\Str, the first argument is the value being filtered, the second argument would be the separator, the third would be language, if a argument name doesn't not exists in the slug method, it will be simply ignored.

Chained usage:

{{ 'john' | ucfirst | substr:start=0,length=1 }} // J
{{ '1999-12-31' | date:format='Y/m/d' }} // 1999/12/31

Passing non-static values:

{{ $name | ucfirst | substr:start=0,length=1 }}
{{ $user['name'] | ucfirst | substr:start=0,length=1 }}
{{ $currentUser->name | ucfirst | substr:start=0,length=1 }}
{{ getName() | ucfirst | substr:start=0,length=1 }}

Passing variables as filter parameters:

$currency = 'HUF'
{{ '12.75' | currency:currency=$currency }} // HUF 12.75

Built-in Laravel functionality:

{{ 'This is a title' | slug }} // this-is-a-title
{{ 'This is a title' | title }} // This Is A Title
{{ 'foo_bar' | studly }} // FooBar

Limitations

Echos

Laravel supports three types of echos. Raw – {!! !!}, regular – {{ }} and escaped (legacy) – {{{ }}}. Filters can be used only with regular echos. Also, filters cannot be used in blade directives directly.

Why? Raw should be as it is. Forced escaping should be escaped only, without modification.

Bitwise operators

Bitwise operators are allowed, but they must be wrapped in parentheses, since they are using the same "pipe operator".

{{ ('a' | 'b') | upper }} // C

The Filters

About the filters

All static methods from Pine\BladeFilters\BladeFilters and \Illuminate\Support\Str are provided as blade filters, it is quite simple, you can also check its source code for reference.

The available filters

The package comes with a few built-in filters, also the default Laravel string methods can be used.

Currency

{{ '17.99' | currency:currency='CHF' }} // CHF 17.99
{{ '17.99' | currency:currency='€',left=false }} // 17.99 €

Passing false as the second parameter will align the symbol to the right.

Date

{{ '1999/12/31' | date }} // 1999-12-31
{{ '1999/12/31' | date:format='F j, Y' }} // December 31, 1999

Lcfirst

{{ 'Árpamaláta' | lcfirst }} // árpamaláta

Unlike PHP's default lcfirst(), this filter works with multi-byte strings as well.

Reverse

{{ 'ABCDEF' | reverse }} //FEDCBA

Substr

{{ 'My name is' | substr:start=0,length=2 }} // My
{{ 'My name is' | substr:start=3 }} // name is

Trim

{{ '   trim me    ' | trim }} // trim me

Ucfirst

{{ 'árpamaláta' | ucfirst }} // Árpamaláta

Unlike PHP's default ucfirst(), this filter works with multi-byte strings as well.

Supported built-in Str functions

• Str::after()
• Str::before()
• Str::camel()
• Str::finish()
• Str::kebab()
• Str::limit()
• Str::plural()
• Str::singular()
• Str::slug()
• Str::snake()
• Str::start()
• Str::studly()
• Str::title()

Custom filter

Add simple custom filter

For the simplest case, you can add custom filter as following

  \Pine\BladeFilters\BladeFilters::macro('script_tag', function (string $asset,$type = 'text/javascript', $async = null, $defer = null) {
      // Your code here
    }
)

Filter provider

You may not need this if you just want to add simple custom filters.

The provided StaticMacroableFilterProvider class allows you to hook static methods and Laravel Macroable as Blade filters. usually, you don't need to add a static macroable class like \Illuminate\Support\Str and \Pine\BladeFilters\BladeFilters, you can use StaticMacroableFilterProvider directly, if you want to support other third party utility classes. for example,

$registry = new BladeFilterProviderRegistry();
$registry
    ->register(new StaticMacroableFilterProvider(\Illuminate\Support\Str::class), 10);

Uncommonly, your filter may be context aware, let's assume a context like this:

A filter named cdn_url which generates url for an asset.

cdn_url('assets/carousel.css');

the domain of the CDN will change depending on the context where the filter run, the context itself is not part of the API of our filter, which the user doesn't need to worry about. you can always pass a variable to your filter as an argument following Pass variables to filter arguments, however, the variable must be filled by the filter's user(you or someone), this is the difference between filter context and filter argument.

filter context is a string which could be a full qualified class name or a variable in Blade view, it must have method access operator( ->, :: ) suffix, an example could be the getFilterContext method of class \Pine\BladeFilters\FilterProvider\StaticMacroableFilterProvider.

    public function getFilterContext(): string
    {
        return sprintf('%s::', $this->class);
    }

Testing

composer install 
./vendor/bin/phpunit