Alinhamento com a última versão do Pix e tratamento do tid

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.1.2
+
+* Alinhamento com a última versão do Pix e tratamento do `tid`;
+
 ## 1.1.1
 
 * Suporte para PHP 7.2

README.md

@@ -6,6 +6,8 @@ O **Pix** é o mais novo método de pagamento eletrônico criado pelo **Banco Ce
 
 Essa biblioteca foi criada para ser utilizada principalmente com o plugin de **Woocommerce** [Pix por Piggly](https://wordpress.org/plugins/pix-por-piggly/). Mas, pode ser utilizada em qualquer sistema onde seja necessário a criação de payloads, códigos e QRCodes Pix.
 
+* Compatível com o Pix versão 2.2.1, veja mais detalhes [clicando aqui](https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/II-ManualdePadroesparaIniciacaodoPix.pdf).
+
 > Confira também nossa micro interface pix em [piggly/php-pix-app](https://github.com/piggly-dev/php-pix-app)
 
 > Se você apreciar a função desta biblioteca e quiser apoiar este trabalho, sinta-se livre para fazer qualquer doação para a chave aleatória Pix `aae2196f-5f93-46e4-89e6-73bf4138427b` ❤.
@@ -69,7 +71,9 @@ Cada campo **EMV®1** contém suas especificações, entre elas o tamanho do cam
 * Chave de E-mail com um valor válido;
 * Chave de Telefone com um valor válido e apenas `numérico`.
 
-> Alguns bancos podem ou não aceitar o caractere `@` para Chaves de E-mail. Atualizamos o plugin para ativar a substituição do `@` por espaço no e-mail `$pix->applyEmailWhitespace()` sinta-se livre para fazer os testes com a sua chave pix.
+> Alguns bancos, por trabalharem com versões antigas do Pix, podem ou não aceitar o caractere `@` para Chaves de E-mail. Atualizamos a biblioteca para ativar a substituição do `@` por espaço no e-mail `$pix->applyEmailWhitespace()` sinta-se livre para fazer os testes com a sua chave pix.
+
+> A partir das versões mais recentes do Pix, ocorreram mudanças no ID da transação para QR Codes estáticos, são elas descritas: O objeto primitivo EMV 62-05 Reference Label, conforme especificado no manual do BR Code, é limitado a 25 caracteres [...] Os caracteres permitidos no contexto do Pix para o campo txid (EMV 62-05) são: `[a-zA-Z0-9]` [...] se o gerador do QR optar por não utilizar um transactionID, o valor "***" deverá ser usado para indicar essa escolha.
 
 ### Classe `Parser`
 
@@ -85,9 +89,9 @@ A classe `Parser` apresenta todos os métodos como `static` e segue o seguinte f
 
 A classe `Payload` é responsável por montar o payload do Pix e segute o seguinte formato:
 
-* O método `applyEmailWhitespace()` determina que o `@` deve ser substituido por um espaço;
-* O método `applyValidCharacters()` determina que acentos e caracteres inválidos como `[\!\.\,\@\#\$\%\&\*\(\)\/\*\?]` deve ser removidos/substituídos nos campos do Pix. Esse efeito é aplicado em `description`, `merchantName`, `merchantCity` e `tid`;
-* * O método `applyUppercase()` transformas todos os caracteres dos campos em maiúsculo. Esse efeito é aplicado em `description`, `merchantName`, `merchantCity` e `tid`;
+* O método `applyEmailWhitespace()` determina que o `@` deve ser substituido por um espaço (para bancos que utilizem versões não atualizadas do Pix);
+* O método `applyValidCharacters()` determina que acentos e caracteres inválidos como `[\!\.\,\@\#\$\%\&\*\(\)\/\*\?]` deve ser removidos/substituídos nos campos do Pix. Esse efeito é aplicado em `description`, `merchantName` e `merchantCity`;
+* * O método `applyUppercase()` transformas todos os caracteres dos campos em maiúsculo. Esse efeito é aplicado em `description`, `merchantName` e `merchantCity`;
 * Métodos com `set` determinam valores para os atributos do Pix;
 * O método `getPixCode()` retorna o código Pix em formato de texto;
 * O método `getQRCode()` retorna uma `string` formatada em `base64`. A saída pode ser controlada com os valores `Payload::OUTPUT_*` para o formato de saída do QR Code e, também, os valores `Payload::ECC_*` para controlar as porcentagens de perca de dados do QR Code.
@@ -132,12 +136,13 @@ Algumas chaves que encontramos incompatibilidades para determinados bancos:
 
 * E-mail: alguns bancos aceitam `@`, outros aceitam espaço e outros aceitam ambos;
 * Telefone: alguns bancos aceitam `+55`, outros ignoram e outros aceitam com e sem `+55`;
+* Transaction ID (tid): alguns bancos não aceitam caracteres diferentes `[a-zA-Z0-9]`, enquanto outros aceitam;
 
 ### Divergências entre Pix Copia & Cola e QR Codes
 
 Há alguns relatos que alguns bancos leem o **QR Code**, mas não leem o **Pix Copia & Cola**. Este não é um problema da biblioteca, o código Pix de ambos são o mesmo! Caso esteja curioso, abra um leitor de QR Code e leia o código é examente o mesmo que o **Pix Copia & Cola**.
 
-Nesse caso, tente utilizar as funções corretivas como `applyEmailWhitespace()`, `applyValidCharacters()` e `applyUppercase()`. Alguns bancos podem ter leituras diferentes e, talvez, existam caracteres inválidos para a leitura do **Pix Copia & Cola**.
+Nesse caso, tente utilizar as funções corretivas como `applyEmailWhitespace()`, `applyValidCharacters()` e `applyUppercase()`. Seu `tid` será automaticamente corrigido para o formato correto. Alguns bancos podem ter leituras diferentes e, talvez, existam caracteres inválidos para a leitura do **Pix Copia & Cola**.
 
 ## Como utilizar?
 

src/Parser.php

@@ -53,40 +53,40 @@ public static function getAlias ( string $key ) : string
 	 * Validate a $value based in the respective pix $key.
 	 * 
 	 * @since 1.0.0
-	 * @param string $key Pix key.
-	 * @param string $value Pix value.
+	 * @param string $keyType Pix key type.
+	 * @param string $value Pix key value.
 	 * @throws Exception
 	 */
-	public static function validate ( string $key, string $value )
+	public static function validate ( string $keyType, string $keyValue )
 	{
-		if ( !in_array($key, [self::KEY_TYPE_RANDOM, self::KEY_TYPE_DOCUMENT, self::KEY_TYPE_EMAIL, self::KEY_TYPE_PHONE]) )
-		{ throw new Exception(sprintf('A chave `%s` é desconhecida.', $key)); }
+		if ( !in_array($keyType, [self::KEY_TYPE_RANDOM, self::KEY_TYPE_DOCUMENT, self::KEY_TYPE_EMAIL, self::KEY_TYPE_PHONE]) )
+		{ throw new Exception(sprintf('A chave `%s` é desconhecida.', $keyType)); }
 
 		$validate = false;
 		$alias    = 'Chave Desconhecida';
 
-		switch ( $key )
+		switch ( $keyType )
 		{
 			case self::KEY_TYPE_RANDOM:
-				$validate = self::validateRandom($value);
-				$alias    = self::getAlias($key);
+				$validate = self::validateRandom($keyValue);
+				$alias    = self::getAlias($keyType);
 				break;
 			case self::KEY_TYPE_DOCUMENT:
-				$validate = self::validateDocument($value);
-				$alias    = self::getAlias($key);
+				$validate = self::validateDocument($keyValue);
+				$alias    = self::getAlias($keyType);
 				break;
 			case self::KEY_TYPE_EMAIL:
-				$validate = self::validateEmail($value);
-				$alias    = self::getAlias($key);
+				$validate = self::validateEmail($keyValue);
+				$alias    = self::getAlias($keyType);
 				break;
 			case self::KEY_TYPE_PHONE:
-				$validate = self::validatePhone($value);
-				$alias    = self::getAlias($key);
+				$validate = self::validatePhone($keyValue);
+				$alias    = self::getAlias($keyType);
 				break;
 		}
 
 		if ( !$validate )
-		{ throw new Exception(sprintf('O valor `%s` para %s está inválido.', $alias, $value)); }
+		{ throw new Exception(sprintf('O valor `%s` para %s está inválido.', $alias, $keyValue)); }
 	}
 
 	/**
@@ -287,6 +287,21 @@ public static function parsePhone ( string $phone ) : string
 		return '+55'.$phone;
 	}
 
+	/**
+	 * Parse transaction id string to valid characters.
+	 * 
+	 * @since 1.1.2
+	 * @param string $phone
+	 * @return string
+	 */
+	public static function parseTid ( string $tid = null )
+	{
+		if ( empty($tid) )
+		{ return '***'; }
+
+		return preg_replace('/[^A-Za-z0-9]+/', '', $tid);
+	}
+
 	/**
 	 * Return the key type based in the pix key.
 	 * 

src/Payload.php

@@ -145,10 +145,11 @@ class Payload
 
 	/**
 	 * Replaces the @ character in e-mail key to a space.
-	 * 
+	 * DEPRECATED:
 	 * @param bool $apply
 	 * @since 1.1.0
 	 * @return self
+	 * @deprecated Aplica-se apenas as versões Pix anteriores a 2.
 	 */
 	public function applyEmailWhitespace ( bool $apply = true ) : self
 	{ $this->emailWhitespace = $apply; return $this; }
@@ -258,11 +259,12 @@ public function setMerchantCity ( string $merchantCity ) : self
 	 * 
 	 * @param string $tid Pix transaction id.
 	 * @since 1.0.0
+	 * @since 1.1.2 Formata o transaction id para formato válido.
 	 * @return self
 	 */
 	public function setTid ( string $tid ) : self
 	{ 
-		$this->tid = $this->applyLength( $this->replacesChar( $this->uppercase( $tid ) ), 25);
+		$this->tid = $this->applyLength( $tid, 25);
 		return $this; 
 	}
 
@@ -513,7 +515,7 @@ protected function getAdditionalDataFieldTemplate ()
 		// Current pix transaction id
 		$tid = $this->formatID(
 			self::ID_ADDITIONAL_DATA_FIELD_TEMPLATE_TID,
-			$this->tid,
+			Parser::parseTid( $this->tid ),
 			false
 		);