From a439c3fc2c3785f36a959c7100994a9547a07a44 Mon Sep 17 00:00:00 2001 From: Mauro Cassani Date: Wed, 26 May 2021 13:24:49 +0200 Subject: [PATCH] Docu --- README.md | 40 +++++++++++++++++++----------- src/AbstractFilter.php | 23 +++++++++++++++++ src/MateCatFilter.php | 24 ------------------ src/MyMemoryFilter.php | 22 ---------------- tests/MateCatSubFilteringTest.php | 4 +-- tests/MyMemorySubFilteringTest.php | 5 ++-- 6 files changed, 53 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index f8d9691..584fbdd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Matecat Subfiltering -Subfiltering is a [Matecat](https://matecat.com) component used for string conversion from database to UI layer and viceversa. +Subfiltering is a component used by [Matecat](https://matecat.com) and [MyMemory](https://mymemory.translated.net/)) for string conversion from database to UI layer and viceversa. ## How to use @@ -9,7 +9,7 @@ There are two filters available (both are implementation of `AbstractFilter`): - `MateCatFilter` - `MyMemoryFilter` -There is a slight difference between the two classes. To instantiate `MateCatFilter` class do the following: +Use `getInstance` method to instantiate these classes: ```php @@ -18,16 +18,7 @@ use Matecat\SubFiltering\MateCatFilter; $filter = MateCatFilter::getInstance(new FeatureSet(), 'it-IT', 'en-EN', []); ``` -Instead to use `MyMemoryFilter` (please note that ): - -```php - -use Matecat\SubFiltering\MyMemoryFilter; - -$filter = MyMemoryFilter::getInstance(new FeatureSet(), 'it-IT', 'en-EN'); -``` - -The only required argument is a concrete implementation of `Matecat\SubFiltering\Contracts\FeatureSetInterface`. +The first argument MUST be concrete implementation of `Matecat\SubFiltering\Contracts\FeatureSetInterface`. There are three more arguments you can pass: @@ -37,7 +28,9 @@ There are three more arguments you can pass: ## Basic Usage -Once `Filter` class is instantiated you can use the following methods to convert strings from one layer to another one: +Once an intance of `AbstractFilter` class is instantiated you can use several methods to convert strings from one layer to another one. + +### MateCatFilter methods - `fromLayer0ToLayer2` - `fromLayer1ToLayer2` @@ -48,7 +41,26 @@ Once `Filter` class is instantiated you can use the following methods to convert - `fromRawXliffToLayer0` - `fromLayer0ToRawXliff` -Where `Layer0` is the DB layer, `Layer1` is the intermediate layer (used by [MyMemory](https://mymemory.translated.net/)) and `Layer2` is the UI layer. +### MyMemoryFilter methods + +- `fromLayer0ToLayer1` +- `fromLayer1ToLayer0` + +Where `Layer0` is the DB layer, `Layer1` is the intermediate layer and `Layer2` is the MateCat's UI layer. + +## Examples + +In the `tests` folder there is an fully working example of a concrete implementation of `FeatureSetInterface` with a custom filter. + +``` +// tests/Mocks +. +├── Features +│   ├── AirbnbFeature.php +│   └── BaseFeature.php +└── FeatureSet.php + +``` ## Support diff --git a/src/AbstractFilter.php b/src/AbstractFilter.php index f96512e..097e0c0 100644 --- a/src/AbstractFilter.php +++ b/src/AbstractFilter.php @@ -65,6 +65,29 @@ protected function setTarget( $target ) $this->target = $target; } + /** + * @param string $source + * @param string $target + * @param FeatureSetInterface $featureSet + * @param array $dataRefMap + * + * @return AbstractFilter + * @throws \Exception + */ + public static function getInstance( FeatureSetInterface $featureSet, $source = null, $target = null, array $dataRefMap = [] ) + { + if ( static::$_INSTANCE === null ) { + static::$_INSTANCE = new static(); + } + + static::$_INSTANCE->setSource($source); + static::$_INSTANCE->setTarget($target); + static::$_INSTANCE->setDataRefMap($dataRefMap); + static::$_INSTANCE->setFeatureSet( $featureSet ); + + return static::$_INSTANCE; + } + /** * Used to transform database raw xml content ( Layer 0 ) to the sub filtered structures, used for server to server ( Ex: TM/MT ) communications ( Layer 1 ) * diff --git a/src/MateCatFilter.php b/src/MateCatFilter.php index 2c4febf..d00be3b 100644 --- a/src/MateCatFilter.php +++ b/src/MateCatFilter.php @@ -3,7 +3,6 @@ namespace Matecat\SubFiltering; use Matecat\SubFiltering\Commons\Pipeline; -use Matecat\SubFiltering\Contracts\FeatureSetInterface; use Matecat\SubFiltering\Filters\CtrlCharsPlaceHoldToAscii; use Matecat\SubFiltering\Filters\DataRefReplace; use Matecat\SubFiltering\Filters\DataRefRestore; @@ -56,29 +55,6 @@ */ class MateCatFilter extends AbstractFilter { - /** - * @param string $source - * @param string $target - * @param FeatureSetInterface $featureSet - * @param array $dataRefMap - * - * @return AbstractFilter - * @throws \Exception - */ - public static function getInstance( FeatureSetInterface $featureSet, $source = null, $target = null, array $dataRefMap = [] ) - { - if ( static::$_INSTANCE === null or !(static::$_INSTANCE instanceof MateCatFilter) ) { - static::$_INSTANCE = new MateCatFilter(); - } - - static::$_INSTANCE->setSource($source); - static::$_INSTANCE->setTarget($target); - static::$_INSTANCE->setDataRefMap($dataRefMap); - static::$_INSTANCE->setFeatureSet( $featureSet ); - - return static::$_INSTANCE; - } - /** * Used to transform database raw xml content ( Layer 0 ) to the UI structures ( Layer 2 ) * diff --git a/src/MyMemoryFilter.php b/src/MyMemoryFilter.php index 5162955..c4de5ba 100644 --- a/src/MyMemoryFilter.php +++ b/src/MyMemoryFilter.php @@ -3,7 +3,6 @@ namespace Matecat\SubFiltering; use Matecat\SubFiltering\Commons\Pipeline; -use Matecat\SubFiltering\Contracts\FeatureSetInterface; use Matecat\SubFiltering\Filters\CtrlCharsPlaceHoldToAscii; use Matecat\SubFiltering\Filters\EncodeToRawXML; use Matecat\SubFiltering\Filters\FromViewNBSPToSpaces; @@ -36,27 +35,6 @@ */ class MyMemoryFilter extends AbstractFilter { - /** - * @param string $source - * @param string $target - * @param FeatureSetInterface $featureSet - * - * @return AbstractFilter - * @throws \Exception - */ - public static function getInstance( FeatureSetInterface $featureSet, $source = null, $target = null ) - { - if ( static::$_INSTANCE === null or !(static::$_INSTANCE instanceof MyMemoryFilter) ) { - static::$_INSTANCE = new MyMemoryFilter(); - } - - static::$_INSTANCE->setSource($source); - static::$_INSTANCE->setTarget($target); - static::$_INSTANCE->setFeatureSet( $featureSet ); - - return static::$_INSTANCE; - } - /** * Used to transform database raw xml content ( Layer 0 ) to the sub filtered structures, used for server to server ( Ex: TM/MT ) communications ( Layer 1 ) * diff --git a/tests/MateCatSubFilteringTest.php b/tests/MateCatSubFilteringTest.php index d60b4bb..b162def 100644 --- a/tests/MateCatSubFilteringTest.php +++ b/tests/MateCatSubFilteringTest.php @@ -3,10 +3,10 @@ namespace Matecat\SubFiltering\Tests; use Matecat\SubFiltering\Commons\Pipeline; -use Matecat\SubFiltering\MateCatFilter; use Matecat\SubFiltering\Filters\LtGtDecode; use Matecat\SubFiltering\Filters\SprintfToPH; use Matecat\SubFiltering\Filters\TwigToPh; +use Matecat\SubFiltering\MateCatFilter; use Matecat\SubFiltering\Tests\Mocks\FeatureSet; use Matecat\SubFiltering\Utils\CatUtils; use PHPUnit\Framework\TestCase; @@ -14,7 +14,7 @@ class MateCatSubFilteringTest extends TestCase { /** - * @return MateCatFilter + * @return \Matecat\SubFiltering\AbstractFilter * @throws \Exception */ private function getFilterInstance() diff --git a/tests/MyMemorySubFilteringTest.php b/tests/MyMemorySubFilteringTest.php index 6bdb872..5639c8d 100644 --- a/tests/MyMemorySubFilteringTest.php +++ b/tests/MyMemorySubFilteringTest.php @@ -2,7 +2,6 @@ namespace Matecat\SubFiltering\Tests; -use Matecat\SubFiltering\MateCatFilter; use Matecat\SubFiltering\MyMemoryFilter; use Matecat\SubFiltering\Tests\Mocks\Features\AirbnbFeature; use Matecat\SubFiltering\Tests\Mocks\FeatureSet; @@ -11,14 +10,14 @@ class MyMemorySubFilteringTest extends TestCase { /** - * @return MateCatFilter + * @return \Matecat\SubFiltering\AbstractFilter * @throws \Exception */ private function getFilterInstance() { $featureSet = new FeatureSet([new AirbnbFeature()]); - return MyMemoryFilter::getInstance($featureSet, 'en-US','it-IT'); + return MyMemoryFilter::getInstance($featureSet, 'en-US','it-IT', []); } public function testVariablesWithHTML()