What does it do?

The TYPO3 Replacer Extension provides a flexible solution for replacing string patterns and regular expressions on your pages. This can be particularly useful for tasks such as replacing URLs for Content Delivery Networks (CDNs) or other customization needs.

Features

• String Pattern Replacement
• Regular Expression Support
• Global Configuration (Enable users to configure replacement rules globally for the entire TYPO3 instance.)
• CDN Integration (It can be used for replacing URLs with CDN links to optimize content delivery)
• Unit Tests & Functional Tests (Include a suite of unit tests to ensure the extension functions correctly and reliably.)

Composer

If your TYPO3 installation works in composer mode, please execute following command:

composer req jweiland/replacer
vendor/bin/typo3 extension:setup --extension=replacer

If you work with DDEV please execute this command:

ddev composer req jweiland/replacer
ddev exec vendor/bin/typo3 extension:setup --extension=replacer

ExtensionManager

On non composer based TYPO3 installations you can install replacer still over the ExtensionManager:

1. Login

   Login to backend of your TYPO3 installation as an administrator or system maintainer.

2. Open ExtensionManager

   Click on Extensions from the left menu to open the ExtensionManager.

3. Update Extensions

   Choose Get Extensions from the upper selectbox and click on the Update now button at the upper right.

4. Install replacer

   Use the search field to find replacer. Choose the replacer line from the search result and click on the cloud icon to install replacer.

Next step

Configure replacer.

Basic search and replace

Imagine you have a website with various content, and throughout the pages, there are instances where the word "apple" is used. You've decided that you want to replace all occurrences of "apple" with "banana".

config.tx_replacer {
  search {
    10 = apple
  }

  replace {
    10 = banana
  }
}

Use a regex as search pattern

Using a regular expression (regex) as a search pattern in the Replacer Extension provides a powerful way to perform complex search and replace operations. Here's an elaboration:

Suppose you have a website with a variety of content, and you want to perform specific text replacements based on patterns that can be defined using regular expressions.

 config.tx_replacer {
   search {
     10 = /apple|raspberry/
     # regular expression replace enabled for this search key
     10.enable_regex = 1
   }

   replace {
      10 = banana
   }
}

Replace pattern only within tags using a regex

It is even possible to replace content just within a specific tag like a parameter.

Replace content within a paragraph

Code:

config.tx_replacer {
  search {
    10 = #(<p[^>]*>.*?)SEARCH(.*?<\/p>)#
    10.enable_regex = 1
  }

  replace {
    10 = $1REPLACE$2
  }
}

Original:

<p class="example">SEARCH</p>

Replaced by:

<p class="example">REPLACE</p>

Replace links for CDN usage

The example TypoScript replaces typo3temp, typo3conf, uploads and fileadmin occurrences with CDN links.

CDN example:

Code:

config.tx_replacer {
  search {
    10 = /"\/?(fileadmin|typo3temp|uploads)/
    10.enable_regex = 1
  }

  replace {
    10 = "https://cdn.tld/$1
  }
}

Original:

<script src="/typo3temp/assets/compressed/example-3b0e5471d7c4492019f42b9ea637ce4e.js"></script>

Replaced by:

<script src="https://cdn.tld/typo3temp/assets/compressed/example-3b0e5471d7c4492019f42b9ea637ce4e.js"></script>

Use stdWrap for search and replacement

You can use stdWrap functionality if you need a more dynamic way to search and replace content. The main step is equal with the basic configuration like above. You can also use a regex as search pattern and a stdWrap as replacement at the same time!

Use page title as replacement

Code:

config.tx_replacer {
  search {
    10 = ###TITLE###
  }

  replace {
    10.stdWrap.field = title
  }
}

Use page modification date as replacement

Code:

config.tx_replacer {
  search {
    10 = ###TIMESTAMP###
  }

  replace {
    # this will replace the timestamp marker in the template with generated value
    10.stdWrap {
    # format like 2017-05-31 09:08
    field = tstamp
    date = Y-m-d H:i
  }
}

More Example with page modification data

The following code can be used to wrap the search parameter with strong tag and the md5 hash of page title.

Code:

config.tx_replacer {
  search {
    10 = hash value to be replaced
  }

  replace {
    10.wrap = <strong>|</strong>
    #replacement will be md5 hash of current page title
    10.field = title
    10.hash = md5
  }
}

We can replace the value in the search key with hash value of the search key by configuring the current property of stdWrap. Here is an example below.

Code:

config.tx_replacer {
  search {
    10 = hash value to be replaced
    10.setContentToCurrent = 1
  }

  replace {
    # replacement will be md5 hash of search key - "hash value to be replaced"
    10.current = 1
    10.wrap = <strong>|</strong>
    10.hash = md5
  }
}

Take a look into the stdWrap documentation for more information.

Update to Version 3.0.0

This version is NOT compatible with PHP versions lower than 7.4! and also the minimum TYPO3 version Compatibility is 11.5.30.

We rewrited the code base and there are so many possibilities and flexibility in configuration possible.

 config.tx_replacer {
   # if this is enabled make sure all search keys should be in regex
   enable_regex = 1
   search {
     10 = /apple|raspberry/
   }

   replace {
      10 = banana
   }
}

 config.tx_replacer {
   search {
     10 = /apple|raspberry/
     10.enable_regex = 1
     20 = keyword
   }

   replace {
      10 = banana
      20 = replacer
   }
}

 config.tx_replacer {
   enable_regex = 1
   search {
     10 = /apple|raspberry/
     20 = /keyword/
   }

   replace {
      10 = banana
      #20 = replacer
   }
}

 config.tx_replacer {
   search {
     10 = /apple|raspberry/
     10.enable_regex = 1
     20 = keyword
   }

   replace {
      10 = banana
      #20 = replacer
   }
}

Version 4.0.2

• [BUGFIX] Fixed cObj initialization issues

Version 4.0.1

• [TASK] Update testing directory

Version 4.0.0

• [TASK] Add support for TYPO3 v13 LTS
• [TASK] Remove support for older TYPO3 versions
• [TASK] Test Suite Updated
• [TASK] Code optimizations and standards applied

Version 3.0.4

• [TASK] Updated TestSuite for GitHub
• [TASK] Formating code lint issues
• [BUGFIX] Handled Type Error when cObj is not ready

Version 3.0.3

• [TASK] Add a lot more func. tests

Version 3.0.2

• [TASK] Update .editorconfig
• [TASK] Rename LICENSE.txt to just LICENSE
• [TASK] Add directories to exclude to .gitattributes
• [TASK] Move TYPO3 const check into new line of ext_localconf.php
• [TASK] Remove unneeded properties from ext_emconf.php

Version 3.0.1

• [BUGFIX] Middleware called in the wrong position where TSFE not initialized

Version 3.0.0

• Add support for TYPO3 v12 LTS
• Better Search and Replace handling
• Documentation updated with several examples and upgrade notes.
• Updated Unit Tests and Functional Tests to TYPO3 Testing Framework

Version 2.1.1

• Minor Bug Fixes

Version 2.1.0

• Add support for TYPO3 v11 LTS

Version 2.0.0

• Add support for TYPO3 11
• Drop support for TYPO3 7 and 8
• Replace deprecated contentPostProc-output hook by middleware
• Check if page contains a USER_INT plugin, otherwise replace the content before caching the page (fixes #11)
• Add new example section to documentation

Version 1.5.1

• Fix outdated $TYPO3_CONF_VARS constant usage

Version 1.5.0

• TYPO3 10 LTS Compatibility

Version 1.4.0

• Feature: Support regular expressions as search pattern
• Bugfix: Run replacer hook nearly at the end

Version 1.3.0

• Allow replacement of uncached content e.g. USER_INT
• Fix dependency to allow TYPO3 > 9.5.0

Version 1.2.0

• Use contentPostProc-all instead of contentPostProc-output (#1)
• Upgrade to work with TYPO3 9.x (#2)

Version 1.1.0

• Version 1.1.0 allows usage of stdWrap for search and replace items.
• Take a look into the documentation for some examples.

Version 1.0.0

• Added Initial release of the Replacer Extension.
• Basic functionality for string pattern replacement.
• Support for global configuration of search and replace patterns.