4SEF hooks

You can modify or extend 4SEF behavior programmatically by using one or more of the hooks listed below. Hooks let you modify internal PHP structures or results computed by 4SEF to better accomodate your website specific requirements.

They are events that are triggered at various moments by 4SEF, providing code you write with internal information and possibly letting you modify this information.

Hooks are not altered when 4SEF is updated

All the customization you do using hooks will survive 4SEF updates. The hooks definition themselves will not change or be removed, unless the corresponding feature is modified or removed from 4SEF of course.

When using hooks with 4SEF, the following apply:

we cannot provide any form of support to the customization you make. You are on your own and the below documentation is the extent of information we'll provide to you.
you'll need suitable programming knowledge and understanding of Joomla internals to be able to write your own hooks handler
you may have to study 4SEF code to learn if what you want to do is possible and how to do it. Again, we won't help you there, at least as part of regular support.

Usage

If you added any hook handler, make sure to absolutely always mention that whenever you open a support ticket. Your custom hooks can alter the way 4SEF works, and may have consequences. We need to be aware of the existence of your hooks at all times.

Types

There are 2 types of hooks: filters and actions. Both are events that are triggered at different moment and to which you can respond.

The difference between them is:

filters: you receive some data, and you can return modified data. 4SEF will subsequently use your modified data
action: you receive some data, but you cannot modify it. Or rather, you can modify it but 4SEF will not use the result anyway

How to

As hooks are basically events, you must register your custom handler with 4SEF for any hook you want to use. 4SEF will then call your handler when the hook is run.

The most convenient way to register your hooks handler and include your custom code is to use 4SEF functions file. The function file is unique and lives at:

/libraries/weeblr/forsef_functions.php

Create the file if it does not exist yet. You can put all your custom code in that file, or just use it to interface with 4SEF and include more PHP code from wherever you want.

The 4SEF function file must always start with:

<?php
/**
 * 4SEF hooks file
 *
 * You can use 2 variables to access 4SEF content:
 *
 * $factory: access variables
 * $hooks: add handlers
 */

// no direct access
defined('WBLIB_EXEC') || die;

If this preamble is missing, just copy/paste it at the top of the file.

After that, you can add your hook handler and your custom code. Here is a typical example, which lets us customize whether 4SEF should leave a given URL as non-SEF:

$hooks->add(
    'forsef_should_leave_non_sef',
    function ($shouldLeaveNonSef, $uri) {

        $option = $uri->getVar('option', '');

        if('com_mycomponent' === $option) {
          $shouldLeaveNonSef = true;
        }

        return $shouldLeaveNonSef;
    }
);

The $hooks variable shown in the example is always available to you inside the functions files, 4SEF creates it for you.

Inside the functions file, you are inside of Joomla, meaning you can use Joomla API as you would in other contexts. You can for instance use the Joomla Factory class to access the application object. Make sure to add the proper namespace use statements if you do so.

API

Below is a list of all 4SEF hooks which allows you to modify or extend its behavior programmatically.

Summary

4SEF currently offers 12 actions in 4 groups.

4SEF currently offers 26 filters in 10 groups.

Actions

4SEF currently offers 12 actions in 4 groups.

Group: Content

`forsef_content_prepared`

Content action

Action to let plugins obtain the finalized content for the current request

@param string $context The context of the content being passed to the plugin. @param mixed $row An object with a "text" property @param mixed $params Additional parameters. See {@see PlgContentContent()}. @param integer $page Optional page number. Unused. Defaults to zero.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 257

Group: Events

`forsef_onAfterDispatch`

Events action

Hook to run the registered onAfterDispatch handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 296

`forsef_onAfterDispatchComplete`

Events action

Hook to run the registered onAfterDispatchComplete handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 329

`forsef_onAfterInitialise`

Events action

Hook to run the registered onAfterInitialise handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 111

`forsef_onAfterRender`

Events action

Hook to run the registered onAfterRoute handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 420

`forsef_onAfterRenderComplete`

Events action

Hook to run the registered onAfterRoute handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 476

`forsef_onAfterRespond`

Events action

Hook to run the registered onAfterRespond handlers.
Warning: body may be gzipped at this time.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 521

`forsef_onAfterRoute`

Events action

Hook to run the registered onAfterRoute handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 186

`forsef_onBeforeCompileHead`

Events action

Hook to run the registered onBeforeCompileHead handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 393

`forsef_onBeforeRender`

Events action

Hook to run the registered onBeforeRender handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 356

Group: Plugins

`forsef_on_load_plugins`

Plugins action

Run an action allowing 3rd-party plugins providers to load
their plugins.

@param \Exception $error

@return void

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/helper/plugins.php
@line 81

Group: Sef

`forsef_url_customized`

Sef action

Run hook after a URL has been customized to allow 3rd-party actions.

@param array $urlPair @param string $originalBasePath @param array $customizedSefs @param string $originalSef @param string $extraPathLeadingSlash @param boolean $customizeDuplicates

@return void

@since 1.0.0 @since 4.6.0 Added $originalSef parameter @since 4.8.0 Added $customizeDuplicates parameter

in /plugins/system/forsef/vendor/weeblr/forsef/data/urlpair.php
@line 617

Filters

4SEF currently offers 26 filters in 10 groups.

Group: Admin

`forsef_admin_ui_constants`

Admin filter

Filter custom CSS for admin.

@param array $uiConstants List of constants related to the specific platform visual display.

@return array

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/view/admin.php
@line 71

`forsef_categories_list`

Admin filter

Filter the list of categories on the site, for user display in the admin.

@param array $categories List of objects each describing a category.

@return array

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/api/controller/categories.php
@line 175

`forsef_custom_admin_css`

Admin filter

Filter custom CSS for admin.

@param string $defaultStyles The raw css to be inserted as style tag in the page.

@return string

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/view/admin.php
@line 90

`forsef_custom_admin_js`

Admin filter

Filter custom JS for admin.

@param string $js The javascript to be inserted into the page with a script tag.

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/view/admin.php
@line 209

`forsef_extensions_list`

Admin filter

Filter the list of extensions installed on the site, for user display in the admin.

@param array $components List of objects each describing an extension.

@return array

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/api/controller/extensions.php
@line 92

Group: Build

`forsef_before_store_url`

Build filter

Filter the built URL pair (sef + nonSef) object just before it's stored to the database. Pagination and suffix has been attached
but dynamic variables are not present as they are not stored to DB. This currently includes:
- /feed/rss and /feed/atom suffixes
- print suffix

@param Data\Urlpair $urlPair @param Uri\Uri $uriToBuild @param Uri\Uri $platformUri

@return void

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/builder.php
@line 391

`forsef_feeds_safe_mode`

Build filter

Filters whether RSS feeds URLS should be built in a safer
way, with format and type passed as query vars instead of
part of the path.
This may be required in some cases, for instance when manually
customizing a category URL to append a prefix to it.

@param bool $safeMode

@return bool

@since 4.6.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/builder.php
@line 714

`forsef_non_sef_vars_to_reappend`

Build filter

Filter the list of non-SEF vars that should be re-appended to the built URL.

@param array $platformQuery @param URI\Uri $uriToBuild @param URI\Uri $platformUri

@return string

@since 1.2.4

in /plugins/system/forsef/vendor/weeblr/forsef/model/urlbuilder.php
@line 184

`forsef_normalize_non_sef`

Build filter

Filters the list of non-sef variables associated with a SEF URL. Some global and plugin-based
modifications to the variables list has already been done, but the full set of original variables
are provided as a reference, as some may need to be put back in under some circumstances.

@param array $vars @param array $originalVars

@return void

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/helper/nonsef.php
@line 207

`forsef_should_leave_non_sef`

Build filter

Filters whether the URL being built should be left non-sef.

@param bool $shouldLeaveNonSef @param Uri $uri

@return bool

@since 1.0.6

in /plugins/system/forsef/vendor/weeblr/forsef/model/builder.php
@line 858

Group: Bundle

`forsef_admin_js_bundle_url`

Bundle filter

Filter main JS bundle URL.

@param string $url The url of the js bundle to be linked from the page.

@return string

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/view/admin.php
@line 108

`forsef_custom_admin_js`

Bundle filter

Filter list of css files to be inserted after main bundle.
Each record added to the lsit must be:
[
'url' => '', mandatory
'options' => [], | []
'attr' => [], | []
]

@param array $cssDefs An array of array[url, options, attr], each defining a link to a css file.

@return string

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/view/admin.php
@line 343

Group: Config

`forsef_config`

Config filter

Filter configuration right after creating it.

@param array $config @param string $scope

@return void

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/config.php
@line 83

`forsef_config_loaded`

Config filter

Filter configuration right after loading it from the database.

@param array $config @param string $scope

@return void

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/config.php
@line 158

Group: Content

`forsef_onContentPrepare`

Content filter

Hook to run the registered onContentPrepare handlers.

@param bool $modified Whether the content was modified. @param string $context The context of the content being passed to the plugin. @param mixed & $row An object with a "text" property @param mixed & $params Additional parameters. See {@see PlgContentContent()}. @param integer $page Optional page number. Unused. Defaults to zero.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 223

`forsef_pagination_chrome_path`

Content filter

Filter path to pagination chromePath file.

@param string $rules Path to an (optional) pagination chrome file.

@return string

@since 1.0.3

in /plugins/system/forsef/platform/overrides/pagination/j4-512/Pagination.php
@line 350

Group: Events

`forsef_onPrivacyCollectAdminCapabilities`

Events filter

Hook to run the registered onAfterInitialise handlers.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 133

Group: Import

`forsef_sh404sef_import_before_store_config`

Import filter

Filter the result of importing sh404SEF configuration, before it is stored to 4SEF database.
Returning an empty value will prevent that config object to be saved at all.

@param Config $configObject @param string $configName

@return Config

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/extensions/sh404sef.php
@line 180

`forsef_sh404sef_import_before_store_url`

Import filter

Filter the result of importing an sh404SEF URL pair, before it is stored to 4SEF database.

@param Data\Urlpair $urlPair @param array $source

@return Data\Urlpair

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/extensions/sh404sef.php
@line 682

Group: Output

`forsef_onAfterRenderComplete_body`

Output filter

Filter the body of the CMS response at onAfterRender.

@param string $body Body of the current request.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 489

`forsef_onAfterRender_body`

Output filter

Filter the body of the CMS response at onAfterRender.

@param string $body Body of the current request.

@since 1.0.0

in /plugins/system/forsef/forsef.php
@line 433

Group: Parse

`forsef_parsed_vars`

Parse filter

Filter parsed variables for the incoming request - or any subsequent call to
Joomla router parsing function.

@param array $vars @param Uri\Uri $uri

@return array

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/parser.php
@line 642

`forsef_redirect_to_correct_case`

Parse filter

Filter whether 4SEF should redirect a request for a URL with a different letter case to
the main one created and recorded in the SEF URLs list.
For instance, if /blog/some-PAGE is requested, and /blog/some-page is
the proper URL, 4SEF will redirect visits to /blog/some-PAGE to /blog/some-page

@param bool $redirectToCorrectCaseEnabled @param string $requestedSef @param string $storedSef

@return bool

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/parser.php
@line 398

`forsef_redirect_to_correct_trailing_slash`

Parse filter

Filter whether 4SEF should redirect a request for a URL non-existing URL
to the same URL with or without a trailing slash if there exists one.
For instance, if /blog/some-page is requested, and does not exists but /blog/some-page/ does exist,
4SEF will redirect visits to /blog/some-page to /blog/some-page/

@param bool $redirectToCorrectSlashEnabled @param string $requestedSef

@return bool

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/parser.php
@line 451

`forsef_request_path_to_parse`

Parse filter

Filter the path 4SEF will try to parse, obtained from the original current URI object.

@param string $originalPath

@return string

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/model/parser.php
@line 144

Group: Request

`forsef_request_info`

Request filter

Filter the list of dynamic variables used in content replacement.

@param array $expandedVariables Array of variable names/variable values to use in expansions.

@return array

@since 1.0.0

in /plugins/system/forsef/vendor/weeblr/forsef/data/requestinfo.php
@line 155