PHPackages                             matecat/subfiltering - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Search & Filtering](/categories/search)
4. /
5. matecat/subfiltering

ActiveLibrary[Search & Filtering](/categories/search)

matecat/subfiltering
====================

Matecat Subfiltering component

v3.0.4(2mo ago)013.9k↓27.3%MITPHPPHP >=8.3

Since May 26Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/matecat/subfiltering)[ Packagist](https://packagist.org/packages/matecat/subfiltering)[ Docs](https://github.com/matecat/subfiltering)[ RSS](/packages/matecat-subfiltering/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (122)Used By (0)

Matecat Subfiltering
====================

[](#matecat-subfiltering)

[![Build Status](https://camo.githubusercontent.com/b5d8b122f1ab32f02d390e6b11dceb2f5bd616c20f8872584dd905f8e64ea3a0/68747470733a2f2f6170702e7472617669732d63692e636f6d2f6d6174656361742f73756266696c746572696e672e7376673f746f6b656e3d7142617a786b4877503138683345576e486a6a46266272616e63683d6d6173746572)](https://app.travis-ci.com/matecat/subfiltering)[![Quality Gate Status](https://camo.githubusercontent.com/f79e9ec7b382fb4f2e027105c246b4f8838c1bdebc88a7a57ec3065c39863e75/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6d6174656361745f73756266696c746572696e67266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/summary/new_code?id=matecat_subfiltering)[![Coverage](https://camo.githubusercontent.com/ef9fe2483b80adfedc9a0afc72d99178bb5a3d54a4b34856f7f901d4daccbed6/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6d6174656361745f73756266696c746572696e67266d65747269633d636f766572616765)](https://sonarcloud.io/summary/new_code?id=matecat_subfiltering)[![Reliability Rating](https://camo.githubusercontent.com/3501dab3ae2e60e2f82fb8b50cc96d593ce7ff0a7fbe0ad73777029f9e6958b8/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6d6174656361745f73756266696c746572696e67266d65747269633d72656c696162696c6974795f726174696e67)](https://sonarcloud.io/summary/new_code?id=matecat_subfiltering)[![Maintainability Rating](https://camo.githubusercontent.com/6d1bd1e49d3cde7714e2074f62669d8174944677aa10ff26d3f7e4e556147aba/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d6d6174656361745f73756266696c746572696e67266d65747269633d7371616c655f726174696e67)](https://sonarcloud.io/summary/new_code?id=matecat_subfiltering)

Subfiltering is a component used by Matecat and MyMemory for converting strings between the database, external services, and the UI layers. It provides a pipeline of filters to safely transform content across these layers while preserving XLIFF tags, HTML placeholders, and special entities.

Overview
--------

[](#overview)

Embedding XML in a REST JSON payload is notoriously hard to render safely and legibly in a web browser. Browsers, frameworks, and JSON serializers all have opinions about angle brackets, entities, and special characters. The result is typically a mix of double-encoding, broken markup, or inline codes that translators can accidentally damage.

This library solves that by introducing reversible “layers” and a transformation pipeline that makes XML- and XLIFF-rich content safe for transport and UI display, while guaranteeing you can restore the exact original.

What makes XML in JSON hard for the browser

- Angle brackets and entities: Raw < and > conflict with HTML, and HTML/JS frameworks may escape or re-escape entities differently than you expect.
- Inline codes in text: XLIFF inline tags (ph, pc, etc.), HTML/XML snippets, ICU, or sprintf tokens can be misinterpreted or edited improperly when shown as-is.
- Safety vs. readability: You need to prevent XSS and layout breakage, but you also need a UI where users can read and edit the text around inline codes.
- Use it when:

    - Your source text includes variables, placeholders, XML, or HTML tags.
    - You must accept user edits while preventing structural damage to tags.
- What it gives you:

    - Converts inline tags to robust placeholders with base64 “memory” of the original, then restores exactly after the round-trip.
    - Prevents double-encoding and protects structural elements.

In short, this library is a bridge between “XML-correct” and “browser-safe,” letting you serve and accept JSON payloads that are straightforward to display and edit in the web UI, while guaranteeing that your original XML/XLIFF structure is preserved perfectly end to end.

How the library addresses it
----------------------------

[](#how-the-library-addresses-it)

- Normalizes and preserves XLIFF tags across transformations.
- Encodes/decodes special characters and placeholders for safe round-trips.
- Converts between three processing layers:

    - Layer 0 (Database): A database-safe XML form, suitable for persistence, export, and exact reconstruction.
    - Layer 1 (External services): A transport-safe form tailored for MT/TM systems that aren’t XML-aware.
    - Layer 2 (UI): A browser/UI-friendly form that replaces raw tags with safe placeholders and base64-backed metadata.
- UI-friendly placeholders

    - XML/XLIFF/HTML tags are converted to stable placeholders with an embedded, base64-encoded “memory” of the original tag.
    - The UI can display and move placeholders without exposing raw markup, reducing the risk of accidental tag damage.
- Reversible roundtrips

    - When the browser sends edited text back, the library restores Layer 2 content to Layer 0, reconstructing the exact original tags from the placeholders.
    - The same applies for Layer 0 ↔ Layer 1 when calling external services.
- Supports XLIFF 2.x dataRef replacement, aligning inline codes from `` with inline tags in segments.

    - If your XLIFF uses originalData with dataRef/dataRefStart/dataRefEnd, the library will create meaningful placeholders for the UI and then restore real XLIFF tags afterward.
    - This keeps both the JSON payload and browser rendering safe without losing fidelity.

Installation
------------

[](#installation)

Install via Composer:

```
bash composer require matecat/subfiltering
```

Requirements:

- PHP 7.4+
- PHPUnit 9.x for running tests (dev)

Filters
-------

[](#filters)

Two concrete filters are provided (both implement `AbstractFilter`):

- `Matecat\SubFiltering\MateCatFilter`
- `Matecat\SubFiltering\MyMemoryFilter`

Create instances using the static `getInstance` factory:

```