Objetivo

Refatorar a arquitetura da biblioteca String Morpher para melhorar manutenibilidade, testabilidade e seguir princípios SOLID, mantendo 100% de compatibilidade com a API existente.

Requisitos Obrigatórios

1. Manter Features Existentes

• ✅ Iniciar com qualquer método estaticamente: SM::sub($string, 3, 5)
• ✅ Iniciar com make(): SM::make($string)->sub(3, 5)
• ✅ Encadeamento fluente retornando sempre a instância
• ✅ Métodos com múltiplos argumentos (ex: sub($offset, $length), replace($needle, $replace, $caseSensitive))
• ✅ Uso como string: echo $string, json_encode(['data' => $string])
• ✅ Método getString() para obter string primitiva

2. Melhorias de Arquitetura

A. Separação de Responsabilidades

• Criar interfaces para contratos claros
• Separar transformers em classes individuais seguindo Strategy Pattern
• Manter a herança atual mas organizar melhor as responsabilidades

B. Adicionar Type Safety

• Adicionar declare(strict_types=1) em todos os arquivos
• Melhorar type hints nos métodos
• Adicionar return types explícitos

C. Estrutura de Diretórios Melhorada

src/
├── Contracts/
│   ├── StringTransformerInterface.php (suporta múltiplos args)
│   └── MaskerInterface.php
├── Transformers/
│   ├── CaseTransformers/
│   ├── ManipulationTransformers/
│   └── EncodingTransformers/
├── Maskers/
│   └── Brazilian/
├── StringMorpher.php (Facade)
└── Instances/
    └── StringMorpherInstance.php

D. Pattern Strategy para Transformers

Cada método deve ser extraído para uma classe transformer, mas mantendo o método na facade para não quebrar a API.

Exemplo de como deve funcionar:

// Interface flexível que suporta múltiplos argumentos
interface StringTransformerInterface
{
    public function transform(string $input, mixed ...$args): string;
}

// Implementação
final class SubTransformer implements StringTransformerInterface
{
    public function transform(string $input, mixed ...$args): string
    {
        [$offset, $length] = $args;
        return substr($input, $offset, $length ?? null);
    }
}

// A facade mantém os métodos mas delega para transformers
class StringMorpher extends BrazilianMasker
{
    public static function sub(string $string, int $offset, ?int $length = null): StringMorpherInstance
    {
        return self::make($string)->sub($offset, $length);
    }
}

// A instância também delega
class StringMorpherInstance extends BrazilianMasker
{
    protected function sub(string $string, int $offset, ?int $length = null): string
    {
        return (new SubTransformer())->transform($string, $offset, $length);
    }
}

3. Qualidade de Código

A. Documentação

• PHPDoc completo em todas as classes e métodos
• Exemplos de uso nos docblocks
• Documentar exceptions que podem ser lançadas

B. Validação de Inputs

• Validar inputs nos métodos críticos (ex: maskers brasileiros)
• Lançar exceptions descritivas quando inputs inválidos

C. Testes

• Manter compatibilidade com testes existentes
• Adicionar testes para novos transformers se necessário

4. Implementação Gradual

Fase 1 - Estrutura Base:

• Criar interfaces e estrutura de diretórios
• Adicionar declare(strict_types=1)
• Melhorar type hints

Fase 2 - Extrair Transformers:

• Criar classes transformer para cada método
• Refatorar métodos para usar transformers internamente
• Manter métodos originais funcionando

Fase 3 - Maskers:

• Organizar maskers brasileiros em namespace próprio
• Adicionar validação de inputs
• Preparar estrutura para outros locales futuros

Constraints

• ❌ NÃO quebrar API existente
• ❌ NÃO remover métodos públicos
• ❌ NÃO mudar assinaturas de métodos existentes
• ❌ NÃO mudar comportamento dos métodos
• ✅ Código deve passar no vendor/bin/phpcs
• ✅ Código deve passar no vendor/bin/phpunit
• ✅ Manter compatibilidade com exemplos da documentação

Exemplo de Uso Após Refatoração

Todos esses usos devem continuar funcionando exatamente como antes:

use SSolWEB\StringMorpher\StringMorpher as SM;

// Uso estático direto
$result = SM::sub('Hello world', 3, 5);
echo $result; // "lo wo"

// Uso com make()
$result = SM::make('Hello world')->sub(3, 5);
echo $result; // "lo wo"

// Encadeamento
$result = SM::make('  hello_world  ')
    ->trim()
    ->toCamelCase()
    ->toUpper();
echo $result; // "HELLOWORLD"

// Como string
$string = SM::make('test')->toUpper();
echo $string; // "TEST"
json_encode(['data' => $string]); // {"data":"TEST"}

// Método getString()
$value = SM::make('test')->toUpper()->getString();
var_dump($value); // string(4) "TEST"

// Métodos com múltiplos args
$result = SM::make('The quick fox')
    ->replace('fox', 'dog', true) // 3 argumentos
    ->padL(20, '-'); // 2 argumentos

Referências

Arquivos atuais da biblioteca:

• src/StringMorpher.php
• src/Instances/StringMorpherInstance.php
• src/Manipulators/Manipulator.php
• src/Manipulators/CaseManipulator.php
• `src/Mas...