Merge branch 'release/v0.5.1' into main

.editorconfig

@@ -0,0 +1,20 @@
+# https://EditorConfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+block_comment_start = /*
+block_comment = *
+block_comment_end = */
+
+[*.yml]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -1,9 +1,11 @@
+.editorconfig export-ignore
 .gitattributes export-ignore
+.github/ export-ignore
 .gitignore export-ignore
 CHANGELOG.md export-ignore
 ecs.php export-ignore
 phpstan.neon export-ignore
 phpunit.xml.dist export-ignore
-README.md export-ignore
-/docs export-ignore
-/tests export-ignore
+docs/ export-ignore
+tests/ export-ignore
+stubs/ export-ignore

.github/workflows/integrate.yml

@@ -0,0 +1,130 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow
+
+name: "Integrate"
+
+on:
+  push:
+    branches:
+      - "develop"
+  pull_request: null
+
+env:
+  PHP_EXTENSIONS: "intl"
+
+jobs:
+  file_consistency:
+    name: "1️⃣ File consistency"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Set up PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "8.0"
+          extensions: "${{ env.PHP_EXTENSIONS }}"
+          ini-values: "post_max_size=256M"
+
+      - name: "Checkout code"
+        uses: "actions/checkout@v3"
+
+      - name: Install Effigy
+        run: |
+          composer global config --no-plugins allow-plugins.phpstan/extension-installer true
+          composer global require decodelabs/effigy
+
+      - name: "Install dependencies"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Check file permissions"
+        run: |
+          composer global exec effigy check-executable-permissions
+
+      - name: "Check exported files"
+        run: |
+          composer global exec effigy check-git-exports
+
+      - name: "Find non-printable ASCII characters"
+        run: |
+          composer global exec effigy check-non-ascii
+
+      - name: "Check source code for syntax errors"
+        run: |
+          composer global exec effigy lint
+
+  static_analysis:
+    name: "3️⃣ Static Analysis"
+    needs:
+      - "file_consistency"
+    runs-on: "ubuntu-latest"
+    strategy:
+      matrix:
+        php-version:
+          - "8.0"
+          - "8.1"
+          - "8.2"
+    steps:
+      - name: "Set up PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          extensions: "${{ env.PHP_EXTENSIONS }}"
+          ini-values: "post_max_size=256M"
+
+      - name: "Checkout code"
+        uses: "actions/checkout@v3"
+
+      - name: Install Effigy
+        run: |
+          composer global config --no-plugins allow-plugins.phpstan/extension-installer true
+          composer global require decodelabs/effigy
+
+      - name: "Validate Composer configuration"
+        run: "composer validate --strict"
+
+      - name: "Install dependencies"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Execute static analysis"
+        run: |
+          composer global exec effigy analyze -- --headless
+
+
+  coding_standards:
+    name: "4️⃣ Coding Standards"
+    needs:
+      - "file_consistency"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Set up PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "8.0"
+          extensions: "${{ env.PHP_EXTENSIONS }}"
+          ini-values: "post_max_size=256M"
+
+      - name: "Checkout code"
+        uses: "actions/checkout@v3"
+
+      - name: "Check EditorConfig configuration"
+        run: "test -f .editorconfig"
+
+      - name: "Check adherence to EditorConfig"
+        uses: "greut/eclint-action@v0"
+
+      - name: Install Effigy
+        run: |
+          composer global config --no-plugins allow-plugins.phpstan/extension-installer true
+          composer global require decodelabs/effigy
+
+      - name: "Install dependencies"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Check coding style"
+        run: |
+          composer global exec effigy format -- --headless
+

CHANGELOG.md

@@ -1,3 +1,10 @@
+## v0.5.1 (2023-09-26)
+* Converted phpstan doc comments to generic
+* Migrated to use effigy in CI workflow
+* Fixed PHP8.1 testing
+* Updated composer check script
+* Updated CI environment
+
 ## v0.5.0 (2022-08-24)
 * Added concrete types to all members
 

README.md

@@ -3,11 +3,17 @@
 [![PHP from Packagist](https://img.shields.io/packagist/php-v/decodelabs/metamorph?style=flat)](https://packagist.org/packages/decodelabs/metamorph)
 [![Latest Version](https://img.shields.io/packagist/v/decodelabs/metamorph.svg?style=flat)](https://packagist.org/packages/decodelabs/metamorph)
 [![Total Downloads](https://img.shields.io/packagist/dt/decodelabs/metamorph.svg?style=flat)](https://packagist.org/packages/decodelabs/metamorph)
-[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/decodelabs/metamorph/PHP%20Composer)](https://github.com/decodelabs/metamorph/actions/workflows/php.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/decodelabs/metamorph/integrate.yml?branch=develop)](https://github.com/decodelabs/metamorph/actions/workflows/integrate.yml)
 [![PHPStan](https://img.shields.io/badge/PHPStan-enabled-44CC11.svg?longCache=true&style=flat)](https://github.com/phpstan/phpstan)
 [![License](https://img.shields.io/packagist/l/decodelabs/metamorph?style=flat)](https://packagist.org/packages/decodelabs/metamorph)
 
-A flexible framework for content transformations
+### A flexible framework for content transformations
+
+Metamorph provides an extensible framework for transforming content from one format to another through a simple and intuitive interface.
+
+_Get news and updates on the [DecodeLabs blog](https://blog.decodelabs.com)._
+
+---
 
 
 ## Installation
@@ -18,7 +24,86 @@ composer require decodelabs/metamorph
 
 ## Usage
 
-Coming shortly...
+### Importing
+
+Metamorph uses [Veneer](https://github.com/decodelabs/veneer) to provide a unified frontage under <code>DecodeLabs\Metamorph</code>.
+You can access all the primary functionality via this static frontage without compromising testing and dependency injection.
+
+
+### Transformations
+
+Use the Metamorph frontage to manipulate and output different formats of content.
+
+Options can be passed as the second parameter and named macros allow for bundles of options to be passed as part of the call.
+
+Metamorph uses [Archetype](https://github.com/decodelabs/archetype) to load `Handler` classes - the base package comes with a small set of handlers out of the box:
+
+
+### Markdown
+
+The built-in Markdown Handler will use whichever appropriate Markdown library has been installed via composer.
+
+```php
+use DecodeLabs\Metamorph;
+
+// Default Markdown renders
+echo Metamorph::markdown($markdownContent);
+
+// Ensure output is secure from exploits with "safe" macro
+echo Metamorph::{'markdown.safe'}($markdownContent);
+
+// Output inline markup
+echo Metamorph::{'markdown.inline'}($markdownContent);
+```
+
+
+### Text
+
+The Text Handler considers input to be plain text and allows for various manipulations.
+HTML wrapping is turned on by default, converting the text to Tagged Markup.
+
+```php
+echo Metamorph::text('Hello world', [
+    'maxLength' => 5 // shorten output with ellipsis
+    'ellipsis' => '...' // Character(s) used while shortening string (optional)
+    'wrap' => true // Wrap output as HTML markup
+]);
+
+// wrap=false
+echo Metamorph::{'text.raw'}($longText);
+
+// maxLength=50, wrap=true
+echo Metamorph::{'text.preview'}($longText);
+
+// maxLength=50, wrap=false
+echo Metamorph::{'text.preview.raw'}($longText);
+```
+
+
+### HtmlToText
+
+The HtmlToText Handler works in the opposite direction, taking HTML input and converting it to readable plain text.
+
+```php
+echo Metamorph::htmlToText('<p>This is an HTML paragraph</p>', [
+    'maxLength' => 5 // shorten stripped output with ellipsis
+    'ellipsis' => '...' // Character(s) used while shortening string (optional)
+    'wrap' => true // Wrap the stripped text in Markup element
+]);
+
+// Strip and re-wrap HTML
+echo Metamorph::{'htmlToText.wrap'}($html);
+
+// maxLength=50, wrap=true
+echo Metamorph::{'htmlToText.preview'}($html);
+```
+
+
+
+## Other implementations
+
+See [Idiom](https://github.com/decodelabs/idiom) and [Chirp](https://github.com/decodelabs/chirp) for other custom implementations of Metamorph Handlers.
+
 
 ## Licensing
 Metamorph is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

composer.json

@@ -19,11 +19,6 @@
         "decodelabs/tagged": "^0.14"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9",
-        "phpstan/phpstan": "^1",
-        "phpstan/extension-installer": "^1.0",
-        "symplify/easy-coding-standard": "^11",
-
         "decodelabs/phpstan-decodelabs": "^0.6",
 
         "soundasleep/html2text": "^1.1",
@@ -42,17 +37,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "0.4.x-dev"
-        }
-    },
-    "config": {
-        "allow-plugins": {
-            "phpstan/extension-installer": true
+            "dev-develop": "0.5.x-dev"
         }
-    },
-    "scripts": {
-        "analyze": "phpstan analyze --no-progress",
-        "psr12": "ecs check --no-progress-bar",
-        "psr12-fix": "ecs check --no-progress-bar --fix"
     }
 }

src/Metamorph.php

@@ -120,15 +120,15 @@ public static function loadHandler(
         $name = $parts[0];
         $macro = $parts[1] ?? null;
 
-        /** @phpstan-var class-string<Handler> */
+        /** @var class-string<Handler> */
         $class = Archetype::resolve(Handler::class, ucfirst($name));
         $reflection = new ReflectionClass($class);
 
         if (
             $reflection->implementsInterface(MacroHandler::class) &&
             $macro !== null
         ) {
-            /** @phpstan-var class-string<MacroHandler> $class */
+            /** @var class-string<MacroHandler> $class */
             $options = array_merge($class::loadMacro($macro) ?? [], $options ?? []);
         }
 

src/Metamorph/Handler/HtmlToText.php

@@ -34,7 +34,7 @@ class HtmlToText implements MacroHandler
 
 
     protected ?int $maxLength = null;
-    protected string $ellipsis = '…';
+    protected string $ellipsis = '…'; // @ignore-non-ascii
     protected bool $wrap = false;
 
     /**