CakePHP em português

Caso você tenha dúvidas, elogios, reclamações, sugestões, etc., acesse o
Grupo de discursão CakePHP-PT e envie uma mensagem.

Instruções gerais

Copie todos os diretórios deste diretório para dentro da pasta app/plugins/cake_ptbr (crie a pasta se necessário).

Para instalar as mensagens de core e as inflections em português, adicione a seguinte linha no arquivo
app/config/bootstrap.php:

require APP . 'plugins' . DS . 'cake_ptbr' . DS . 'config' . DS . 'bootstrap.php';

O código anterior não é necessário para utilização dos behaviors e helpers.

Todos os recursos possuem testes unitários.

Recursos disponíveis no plugin

Traduzindo as mensagens do core – Referência

Ao incluir a linha no bootstrap (conforme as instruções nas informações gerais), as mensagens geradas pelo CakePHP serão traduzidas
para português brasileiro. Frases de estar faltando controller, view, etc. são exemplos de frases que serão traduzidas.

Inflections – Referência

Inflections são regras de como as palavras serão pluralizadas e singualizadas. O CakePHP nativamente trás as regras para o inglês,
porém as palavras em português ficam erradas. Por exemplo, nativamente o CakePHP considera a palavra ‘computadors’ como o plural de
‘computador’.

As inflections afetam também as palavras usadas como nome de tabelas no banco de dados.

EstadoBrasileiro (Model)

O model EstadoBrasileiro contém informações sobre os estados brasileiros, podendo ser utilizado para auxiliar ou associar com outros
modelos. Também poderá servir de base para outros modelos.

Instalação e Utilização

Utilizar no controller:

class XxxsController extends AppController {
	var $name = 'Xxxs';
	var $uses = array('Xxx', 'CakePtbr.EstadoBrasileiro');

	function index() {
		$this->EstadoBrasileiro->find('list');
	}
}

Criando uma model:

App::import('Model', 'CakePtbr.EstadoBrasileiro');

class Estado extends EstadoBrasileiro {
...
}

A model EstadoBrasileiro estende a AppModel. Logo, todos os métodos utilizados na sua AppModel serão aplicados neste novo model.

Métodos disponíveis no model:

• listaEstados($incluirDF = true)
  • Gera uma lista com os estados, sendo a chave a sigla e o valor o nome do estado.
• todosEstados($incluirDF = true)
  • Lista os estados, mas no formato array(‘EstadoBrasileiro’ => array(array(‘sigla’ => ‘SC’, ‘nome’ => ‘Santa Catarina’), …)).
• estadoPorSigla($sigla)
  • Informa o nome do estado através da sigla. Por exemplo, passando ‘SC’ como parâmetro, é retornado ‘Santa Catarina’.
• siglaPorEstado($estado)
  • Inverso do método anterior.
• estadosDoSul()
  • Apresenta uma lista com os estados da região sul. A lista virá no mesmo formato de listaEstados.
• estadosDoSudeste()
  • Idem estadosDoSul, mas para região sudeste.
• estadosDoCentroOeste($incluirDF = true)
  • Idem estadosDoSul, mas para região centro-oeste. É possível informar se será incluído o Distrito Federal.
• estadosDoNorte()
  • Idem estadosDoSul, mas para região norte.
• estadosDoNordeste()
  • Idem estadosDoSul, mas para região nordeste.

Validação (Behavior) – Referência

O behavior Validacao serve para fazer validações de CPF, CNPJ, CEP e número de telefone.

Instalação

Adicione o behavior ‘CakePtbr.Validacao’ no seu model através da variável actsAs. Exemplo:

class Usuario extends AppModel {
	var $name = 'Usuario';
	var $actsAs = array('CakePtbr.Validacao');
}

Utilização

CPF

	var $validates = array(
		'cpf' => array(
			'rule' => 'cpf'
		)
	);

Se a regra for declarada apenas como cpf (idem exemplo acima), ele irá validar o CPF no formato XXX.XXX.XXX-XX e também fará
o teste do dígito verificador (dois últimos números) para verificar se é um CPF válido. Em determinadas situações, deseja-se
enviar pro banco apenas os números, sem a formatação, pra isso, coloquei um parâmetro opcional que pode ser passado para fazer
este teste. Na rule, deve ser colocado:

	var $validates = array(
		'cpf' => array(
			'rule' => array('cpf', true)
		)
	);

Deste modo ele irá validar apenas números.

CNPJ

Mesmo funcionamento do CPF, porém para CNPJ. A regra de apenas números também é válida. O formato do CPNJ é considerado XX.XXX.XXX/XXXX-XX.

CEP

O CEP, por padrão vai ser considerado nos formatos XXXXXXXX ou XXXXX-XXX. Caso queira alterar o separador, você pode definir da seguinte maneira:

	var $validates = array(
		'cep' => array(
			'rule' => array('cep', array('', '-', '.'))
		)
	);

No exemplo acima, ele vai validar os valores padrões e XXXXX.XXX.

Telefone

A validação do telefone se dará através das formatações:

• XXXX-XXXX
• (XX) XXXX-XXX (o espaço entre o fechamento de parênteses e o número é opcional, mas limitado a 1 espaço)
• +XX (XX) XXXX-XXXX (idem anterior sobre o espaçamento)

Correios (Behavior) – Referência

Métodos para acessar recursos dos Correios brasileiro.

Instalação

Adicione o behavior ‘CakePtbr.Correios’ no seu model através da variável actsAs. Exemplo:

class Entrega extends AppModel {
	var $name = 'Entrega';
	var $actsAs = array('CakePtbr.Correios');
}

Utilização

Cálculo de valor de frete

O método para calcular o frete chama-se ‘valorFrete’ e tem os seguintes parâmetros:

• servico: define o tipo de serviço que será feito. Os valores válidos são através das constantes: CORREIOS_SEDEX, CORREIOS_SEDEX_A_COBRAR, CORREIOS_SEDEX_10, CORREIOS_SEDEX_HOJE, CORREIOS_E_SEDEX, CORREIOS_ENCOMENDA_NORMAL, CORREIOS_PAC.
• cepOrigem: Cep de origem no formato XXXXX-XXX.
• cepDestino: Cep de destino no formato XXXXX-XXX.
• peso: Peso, em quilos, do item a ser transportado. O valor deve ser um número e não deve ultrapassar 30.
• maoPropria:(opcional. Padrão falso) Valor boleano para indicar se o transporte é com mão prórpria.
• valorDeclarado: (opcional. Padrão 0.00) Valor do item a ser transportado.
• avisoRecebimento: (opcional. Padrão falso) Calculo com aviso de recebimento.

O retorno será negativo em caso de erro, que podem ser as constantes:

• ERRO_CORREIOS_PARAMETROS_INVALIDOS: Um ou mais parâmetros com formato ou conteúdo inválido.
• ERRO_CORREIOS_EXCESSO_PESO: Peso acima do limite (30 Kg).
• ERRO_CORREIOS_FALHA_COMUNICACAO: Problema de comunicação com o site dos Correios.
• ERRO_CORREIOS_CONTEUDO_INVALIDO: O conteúdo retornado pelo Correios não é o esperado.

Em caso de sucesso, será retornado um array com os seguintes indices:

• ufOrigem: UF da Origem
• ufDestino: UF do Destino
• capitalOrigem: Valor booleano indicando se a origem é considerada capital
• capitalDestino: Valor booleando indicando se o destino é considerado capital
• valorMaoPropria: Valor, em reais, da mão própria
• valorTarifaValorDeclarado: Valor da tarifa pelo valor declarado
• valorFrete: Valor apenas do frente, sem incluir os valores de mão própria e tarifa do valor declarado
• valorTotal: Soma de todos os valores anteriores

Exemplo de uso:

class Entrega extends AppModel {
	var $name = 'Entrega';
	var $actsAs = array('CakePtbr.Correios');

	function frete($cepDestino) {
		// Supondo que é uma loja que transporta produtos pequenos (até 1Kg)
		return $this->valorFrete(CORREIOS_SEDEX, Configure::read('Loja.CEP'), $cepDestino, 1.0);
	}
}

Endereço de um CEP

O método ‘endereco’ informa o endereço baseado em algum CEP. O único parâmetro é o CEP no formato XXXXX-XXX. Os valores de retorno podem
ser as constantes ERRO_CORREIOS_PARAMETROS_INVALIDOS, ERRO_CORREIOS_FALHA_COMUNICACAO ou ERRO_CORREIOS_CONTEUDO_INVALIDO em caso de erro.
Em caso de sucesso, o retorno será um array com os indices logradouro, bairro, cidade e uf.

Exemplo de uso:

class Endereco extends AppModel {
	var $name = 'Endereco';
	var $actsAs = array('CakePtbr.Correios');
 
	function beforeSave($options) {
		$endereco = $this->endereco($this->data['Endereco']['CEP']);
		if ($endereco < 0) {
			return false;
		}
		$this->data['Endereco'] = array_merge($this->data['Endereco'], $endereco); // Aqui serão incluídas as informações de logradouro, bairro, cidade e uf.
	}
}

AjusteData (Behavior)

Behavior para ajustar as horas no formato dd/mm/yyyy para o formato SQL (yyyy-mm-dd).

Instalação

Adicione o behavior ‘CakePtbr.AjusteData’ no seu model através da variável actsAs, porém neste behavior tem uma diferença em relação aos demais.
É possível adicionar o behavior de três maneiras:

• Não informando os campos: Neste caso, o behavior buscará automaticamente todos os campos do tipo date no model, exceto os campos update,
  create e modified;
• Informando como string: Será considerado apenas o campo da string;
• Informando um array: Cada item do array será considerado um campo para alteração do formato.

Exemplo:

class Noticia extends AppModel {
	var $name = 'Noticia';
	var $actsAs = array('CakePtbr.AjusteData'); // Primeiro caso
	var $actsAs = array('CakePtbr.AjusteData' => 'campo_data'); // Segundo caso
	var $actsAs = array('CakePtbr.AjusteData' => array('publicado', 'informado')); // Terceiro caso
}

Utilização

A utilização é automática.

Funcionamento

Na sua view, o usuário vai preencher um campo com o formato dd/mm/yyyy, porém este campo deve ser alterado para ser cadastrado no banco
de dados. Para evitar que isto seja no controller ou num beforeSave de vários models, basta incluir este behavior.

Antes de cada save o behavior ajusta as datas dos campos informados (ou encontrados automaticamente) e então envia para o banco de dados
com os valores corretos.

Ao resgatar o registro do banco, este behavior NÃO transforma para o formato brasileiro, pois o model manipula dados e não formatações.
Caso você vá exibir a data, use o helper de formatação deste plugin.

Formatação (Helper) – Referência

Helper para formatação de datas e números no formato brasileiro.

Instalação

Adicione o helper ‘CakePtbr.Formatacao’ no seu controller através da variável helpers. Exemplo:

class PedidosControllers extends AppController {
	var $name = 'Pedidos';
	var $helpers = array('CakePtbr.Formatacao');

	function index() {
		// Qualquer código...
	}
}

Utilização

Abaixo segue a lista dos métodos existentes no helper, com os parâmetros esperados e uma breve descrição.

• data($data = null)
  • Formata uma data timestamp no formato dd/mm/YYYY. Se não for informada a data, será utilizada a data atual
• dataHora($dataHora = null, $segundos = true)
  • Idem anterior, porém com a informação da hora junto.
• dataCompleta($dataHora = null)
  • Mostra a data completa. Exemplo: ‘terça-feira, 21 de abril de 2009, 10:00:00′.
• precisao($numero, $casasDecimais = 3)
  • Similar ao método precision do helper Time, mostrando os números no formato brasileiro.
• porcentagem($numero, $casasDecimais = 2)
  • Mostra o valor em porcentos, similar ao toPorcentage do TimeHelper.
• moeda($valor, $opcoes = array())
  • Mostra o valor em reais. Exemplo: R$ 10,20.
• moedaPorExtenso($numero)
  • Escreve o valor por extenso, em reais.

Estados (Helper)

Helper para apresentar os estados brasileiros.

Instalação

Adicione o helper ‘CakePtbr.Estados’ no seu controller através da variável helpers. Exemplo:

class PedidosControllers extends AppController {
	var $name = 'Pedidos';
	var $helpers = array('CakePtbr.Estados');

	function index() {
		// Qualquer código...
	}
}

Utilização

Na sua view, utilizar da forma similar ao método select do helper Form, exceto pelo parâmetro options. Exemplo:

echo $estados->select('Model.uf'); // Exibirá um select com todos os estados
echo $estados->select('Model.uf', 'SC'); // Exibirá um select com todos os estados, deixando Santa Catarina como selecionada
echo $estados->select('Model.uf', null, array('uf' => true)); // Exibirá o select. O valor que irá aparecer serão apenas as siglas

Em todos os casos anteriores, o valor do campo será a sigla (2 caracteres). Vale lembrar que é possível
utilizar todos os mesmos parâmetros do select do form , exceto o campo $options, que foi
suprimido. Além disso, o valor padrão de $showEmpty agora é false ao invés de '' (ou seja, não irá apresentar campo vazio).