Custom Pipe Functions

Automad already provides a set of pipe functions to modify the value of a variable. However, in some cases it may be necessary to use a custom function to process the content of a variable. Custom pipe functions are written in plain PHP and their setup is very similar to the structure of a generic extension.

@{ variable | Vendor/Name }

Package Structure

Like themes and generic extensions, custom pipe functions are added to an Automad installation in form of a package. Also here, there are two types of packages: local packages and Composer packages.

Local Packages

The most simple structure of a custom pipe function package is a directory for your namespace inside the packages directory, containing a directory for your function that shares the same name as the PHP file inside. Note that all file and directory names must be lowercase.

packages/
  vendor/
    name/
      name.php

According to the directory structure above, the PHP file of the pipe function looks like this:

<?php

// The namespace corresponds to the directory structure.
namespace Vendor;

// Prevent direct access.
defined('AUTOMAD') or die('Direct access not permitted!');

// The class name corresponds to the function directory and file name.
class Name {
  // The main method must have the same name as the class.
  public function Name(string $value): string {
    // Modify the value here.
    return $value;
  }
}

Now the custom pipe function can be used in templates as follows:

@{ variable | Vendor/Name }

Composer Packages

In Composer packages, classes are loaded by the autoloader of Composer, which allows for a more flexible file structure. The only important convention is that the main method has the same name as the class. Custom pipe functions that are loaded by Composer are called in templates by the combination of their namespace and their class name. Add a composer.json file with the following content to the root of your package:

{
  "name": "vendor/name",
  "description": "The pipe function description ...",
  "type": "automad-package",
  "keywords": ["extension"],
  "license": "MIT",
  "require": {
    "automad/package-installer": "^1.1"
  },
  "autoload": {
    "classmap": [""]
  }
}

Find more information about publishing packages on the packages page.

Parameters

When a custom pipe function is called, the value of the variable is always passed as the first argument. Additional parameters can be passed in parentheses in the template:

@{ variable | Vendor/Name ('first', 'second') }

Those parameters are simply appended to the list of arguments of the main method after the value of the variable:

<?php

namespace Vendor;

defined('AUTOMAD') or die('Direct access not permitted!');

class Name {
  public function Name(string $value, string $prefix = '', string $suffix = ''): string {
    return $prefix . $value . $suffix;
  }
}

Return Values

The modified value has to be returned using a return statement. The returned value is then either passed to the next pipe function in the chain or rendered as the output of the variable statement.

@{ title | Vendor/Name ('[', ']') | strtoupper }