Add FormatterBuilder for fluent formatter chaining #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

henriquemoody merged 1 commit into Respect:main from henriquemoody:formatter_builder

Jan 30, 2026

README.md

-Original file line number
+Diff line change
@@ Expand Up @@
     composer require respect/string-formatter
     ```
+    ## Usage
+    You can use individual formatters directly or chain multiple formatters together using the `FormatterBuilder`:
+    ```php
+    use Respect\StringFormatter\FormatterBuilder as f;
+    echo f::create()
+        ->mask('7-12')
+        ->pattern('#### #### #### ####')
+        ->format('1234123412341234');
+    // Output: 1234 12** **** 1234
+    ```
     ## Formatters
     | Formatter                                            | Description                                         |
@@ Expand Down @@

phpunit.xml.dist

-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,9 @@ @@
              xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
              cacheDirectory=".phpunit.cache">
       <testsuites>
+        <testsuite name="integration">
+          <directory>tests/Integration/</directory>
+        </testsuite>
         <testsuite name="unit">
           <directory>tests/Unit/</directory>
         </testsuite>
@@ Expand Down @@

src/FormatterBuilder.php

-Original file line number
+Diff line change
@@ -0,0 +1,63 @@
+    <?php
+    /*
+     * SPDX-FileCopyrightText: (c) Respect Project Contributors
+     * SPDX-License-Identifier: ISC
+     * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+     */
+    declare(strict_types=1);
+    namespace Respect\StringFormatter;
+    use ReflectionClass;
+    use Respect\StringFormatter\Mixin\Builder;
+    use function array_reduce;
+    use function ucfirst;
+    /** @mixin Builder */
+    final readonly class FormatterBuilder implements Formatter
+    {
+        /** @var array<Formatter> */
+        private array $formatters;
+        public function __construct(Formatter ...$formatters)
+        {
+            $this->formatters = $formatters;
+        }
+        public static function create(Formatter ...$formatters): self
+        {
+            return new self(...$formatters);
+        }
+        public function format(string $input): string
+        {
+            if ($this->formatters === []) {
+                throw new InvalidFormatterException('No formatters have been added to the builder');
+            }
+            return array_reduce(
+                $this->formatters,
+                static fn(string $carry, Formatter $formatter) => $formatter->format($carry),
+                $input,
+            );
+        }
+        /** @param array<int, mixed> $arguments */
+        public function __call(string $name, array $arguments): self
+        {
+            /** @var class-string<Formatter> $class */
+            $class = __NAMESPACE__ . '\\' . ucfirst($name) . 'Formatter';
+            $reflection = new ReflectionClass($class);
+            return clone($this, ['formatters' => [...$this->formatters, $reflection->newInstanceArgs($arguments)]]);
+        }
+        /** @param array<int, mixed> $arguments */
+        public static function __callStatic(string $name, array $arguments): self
+        {
+            return self::create()->__call($name, $arguments);
+        }
+    }

src/Mixin/Builder.php

-Original file line number
+Diff line change
@@ -0,0 +1,24 @@
+    <?php
+    /*
+     * SPDX-FileCopyrightText: (c) Respect Project Contributors
+     * SPDX-License-Identifier: ISC
+     * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+     */
+    declare(strict_types=1);
+    namespace Respect\StringFormatter\Mixin;
+    use Respect\StringFormatter\FormatterBuilder;
+    /** @mixin FormatterBuilder */
+    interface Builder
+    {
+        public static function mask(string $range, string $replacement = '*'): Chain;
+        public static function pattern(string $pattern): Chain;
+        /** @param array<string, mixed> $parameters */
+        public static function placeholder(array $parameters): Chain;
+    }

src/Mixin/Chain.php

-Original file line number
+Diff line change
@@ -0,0 +1,24 @@
+    <?php
+    /*
+     * SPDX-FileCopyrightText: (c) Respect Project Contributors
+     * SPDX-License-Identifier: ISC
+     * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+     */
+    declare(strict_types=1);
+    namespace Respect\StringFormatter\Mixin;
+    use Respect\StringFormatter\Formatter;
+    use Respect\StringFormatter\FormatterBuilder;
+    interface Chain extends Formatter
+    {
+        public function mask(string $range, string $replacement = '*'): FormatterBuilder;
+        public function pattern(string $pattern): FormatterBuilder;
+        /** @param array<string, mixed> $parameters */
+        public function placeholder(array $parameters): FormatterBuilder;
+    }

tests/Integration/FormatterBuilderTest.php

-Original file line number
+Diff line change
@@ -0,0 +1,198 @@
+    <?php
+    /*
+     * SPDX-FileCopyrightText: (c) Respect Project Contributors
+     * SPDX-License-Identifier: ISC
+     * SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
+     */
+    declare(strict_types=1);
+    namespace Respect\StringFormatter\Test\Integration;
+    use ArgumentCountError;
+    use Error;
+    use PHPUnit\Framework\Attributes\CoversClass;
+    use PHPUnit\Framework\Attributes\Test;
+    use PHPUnit\Framework\TestCase;
+    use ReflectionException;
+    use Respect\StringFormatter\FormatterBuilder;
+    use Respect\StringFormatter\InvalidFormatterException;
+    use Respect\StringFormatter\MaskFormatter;
+    use Respect\StringFormatter\PatternFormatter;
+    use Respect\StringFormatter\PlaceholderFormatter;
+    use function sprintf;
+    #[CoversClass(FormatterBuilder::class)]
+    final class FormatterBuilderTest extends TestCase
+    {
+        #[Test]
+        public function itShouldFormatWithSingleFormatter(): void
+        {
+            $input = '1234123412341234';
+            $range = '1-3,8-12';
+            $maskFormatter = new MaskFormatter($range);
+            $expected = $maskFormatter->format($input);
+            $builder = new FormatterBuilder();
+            $actual = $builder->mask($range)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldFormatWithMultipleFormatters(): void
+        {
+            $input = '1234123412341234';
+            $range = '1-3,8-12';
+            $pattern = '#### #### #### ####';
+            $maskFormatter = new MaskFormatter($range);
+            $patternFormatter = new PatternFormatter($pattern);
+            $expected = $patternFormatter->format($maskFormatter->format($input));
+            $builder = new FormatterBuilder();
+            $actual = $builder->mask($range)->pattern($pattern)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldThrowExceptionWhenFormattingWithoutFormatters(): void
+        {
+            $builder = new FormatterBuilder();
+            $this->expectException(InvalidFormatterException::class);
+            $this->expectExceptionMessage('No formatters have been added to the builder');
+            $builder->format('test');
+        }
+        #[Test]
+        public function itShouldAllowCallingSameFormatterMultipleTimes(): void
+        {
+            $input = '1234567890';
+            $firstRange = '1-3';
+            $secondRange = '5-7';
+            $firstMaskFormatter = new MaskFormatter($firstRange);
+            $secondMaskFormatter = new MaskFormatter($secondRange);
+            $expected = $secondMaskFormatter->format($firstMaskFormatter->format($input));
+            $builder = new FormatterBuilder();
+            $builder = $builder->mask($firstRange)->mask($secondRange);
+            $actual = $builder->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldCreateMaskFormatterUsingStaticFactory(): void
+        {
+            $input = '1234567890';
+            $range = '1-3';
+            $maskFormatter = new MaskFormatter($range);
+            $expected = $maskFormatter->format($input);
+            $actual = FormatterBuilder::mask($range)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldCreatePatternFormatterUsingStaticFactory(): void
+        {
+            $input = '1234567890';
+            $pattern = '###-###-####';
+            $patternFormatter = new PatternFormatter($pattern);
+            $expected = $patternFormatter->format($input);
+            $actual = FormatterBuilder::pattern($pattern)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldCreatePlaceholderFormatterUsingStaticFactory(): void
+        {
+            $input = 'Hello, {{name}}!';
+            $parameters = ['name' => 'World'];
+            $placeholderFormatter = new PlaceholderFormatter($parameters);
+            $expected = $placeholderFormatter->format($input);
+            $actual = FormatterBuilder::placeholder($parameters)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldUsePlaceholderFormatter(): void
+        {
+            $input = 'Hello, {{name}}! Your balance is {{amount}}.';
+            $parameters = [
+                'name' => 'John',
+                'amount' => 100.5,
+            ];
+            $expected = (new PlaceholderFormatter($parameters))->format($input);
+            $builder = new FormatterBuilder();
+            $actual = $builder->placeholder($parameters)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldBuildFormatterWithMultipleArguments(): void
+        {
+            $input = '1234567890';
+            $range = '1-3,7-9';
+            $replacement = 'X';
+            $maskFormatter = new MaskFormatter($range, $replacement);
+            $expected = $maskFormatter->format($input);
+            $builder = new FormatterBuilder();
+            $actual = $builder->mask($range, $replacement)->format($input);
+            self::assertSame($expected, $actual);
+        }
+        #[Test]
+        public function itShouldThrowExceptionWhenFormatterIsNotInstantiable(): void
+        {
+            $builder = new FormatterBuilder();
+            $this->expectException(Error::class);
+            $this->expectExceptionMessage('Cannot instantiate interface Respect\StringFormatter\Formatter');
+            $builder->__call('', []);
+        }
+        #[Test]
+        public function itShouldThrowExceptionWhenFormatterArgumentIsMissing(): void
+        {
+            $builder = new FormatterBuilder();
+            $this->expectException(ArgumentCountError::class);
+            $this->expectExceptionMessage(sprintf(
+                'Too few arguments to function %s::__construct(), 0 passed and exactly 1 expected',
+                PatternFormatter::class,
+            ));
+            /** @phpstan-ignore arguments.count */
+            $builder->pattern();
+        }
+        #[Test]
+        public function itShouldThrowExceptionWhenFormatterDoesNotExist(): void
+        {
+            $builder = new FormatterBuilder();
+            $this->expectException(ReflectionException::class);
+            $this->expectExceptionMessage('Class "Respect\StringFormatter\NonexistentFormatter" does not exist');
+            /** @phpstan-ignore method.notFound */
+            $builder->nonexistent();
+        }
+    }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add FormatterBuilder for fluent formatter chaining #3

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!