Custom Pipe Functions

Automad provides already some basic string manipulation functions to be used with the pipe operator. However, in some cases it my be necessary to use a custom function to modify the content of a variable. Custom pipe functions can be written in plain PHP. Thier basic setup is very similar to the structure of a generic extension.

Package Structure

Like themes or generic extensions, custom pipe functions have to be added to an Automad installation in form of a package or as part of it. There are basically two types of custom pipe function packages: local packages and Composer packages. Similar to generic extensions, also here the main difference between them is the way autoloading PHP classes is handled.

Local Packages

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

packages/
  yournamespace/
    yourextension/
      yourextension.php

According to the directory structure above, the pipe function's PHP file will look like this:

<?php
// Namespace corresponding to your directory structure.
namespace YourNamespace;
// Prevent direct access to the extension to enhance security.
defined('AUTOMAD') or die();
// The class name corresponds to the extension directory and file name.
class YourExtension {
    // The main method of your extension. 
    // Note that the method name must be the same as the class name.
    public function YourExtension($value) {
        // Your extension code goes here.
        return $value;
    }
}
?>

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

@{ variable | yournamespace/yourextension }

Composer Packages

In contrast to local packages, the autoloading of PHP classes is handled differently in Composer packages. Since Composer registeres all used classes in file called autoload.php on installation, you are more flexible with the file structure of your package. The only important convention to follow is that the main function has the same name as the class itself. Note that extensions using the Composer autoloader can be called in templates by using a combination of their namespace and their class name.

@{ variable | Namespace/Class }

To make sure your extension is autoloaded correctly by Composer, you will have to add a composer.json file with the following content to the root of your package:

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

Find more information about publishing extensions here.

Function Parameters

When the extension is called by a template, there is always the value of the variable passed to the function as the first parameter. For example a simple function without any additional parameters can be used in a template like this:

@{ variable | YourNamespace/YourExtension }

The PHP file with the corresponding function code will the look as follows:

<?php
namespace YourNamespace;
class YourExtension {
    public function YourExtension($value) {
        // Use some PHP code to manipulate the content of the 
        // variable passed as $value and then return it.
        return $value;
    }
}

Additional Parameters

It is also possible to pass one or more additional parameters to a custom pipe function like this in templates:

@{ variable | YourNamespace/YourExtension ('...', '...') }

Those parameters can be used in the PHP code of the function by appending them to the list of parameters after the main value of the variable as follows:

<?php
namespace YourNamespace;
class YourExtension {
    public function YourExtension($value, $parameter1, $parameter2) {
        ...
        return $value;
    }
}

Return Values

The modified $value of the custom pipe function simply has to be returned using PHPsreturn` statement to either be passed to the next chained function or as the output of the variable statement in a template.