Manual das Funções Instar

Faz-se necessário que a Instar tenha uma padronização de código legível e segura para todos os seus sistemas, e essa padronização se resolve com as funções instar. Hoje temos uma mistura de maneiras de utilização, algumas delas inseguras, obsoletas, ou de difícil entendimento, o problema é que mesmo assim elas ainda funcionam então para ganhar tempo em um sistema onde tem muitas coisas elas vão sendo copiadas. A Instar já definiu os produtos foco nos próximos anos, quais sejam: Instar SWOP, Instar SWE e Instar MAIL. Futuramente todos os códigos, pelo menos desses sistemas, devem estar padronizados garantindo uma melhor organização.
As “funções instar”, são classes e dentro dessas classes existem os métodos. Introduziremos quais são elas e seus métodos abaixo:

1. Banco de Dados (instar_funcoes_bd.class.php)

Para acesso ao banco de dados é utilizada a classe instar_funcoes_bd.class.php

Essa classe é responsável pela manipulação de banco de dados independentemente do banco, com consultas em português, segurança e facilidade.
Por padrão ela vem com a função debug desativada, quando você estiver em desenvolvimento convém ativar essa função para receber os erros detalhados de suas consultas.

< ? php 
					$instar->debug = true;
?>

1.1) Instanciando a Classe

Em nossos sistemas ela já é instanciada na variável $instar, porém se for necessário manipular outro banco de dados na aplicação é possível fazendo a instanciação de outro banco de dados da seguinte forma:

< ? php 
					
$conexao = new instar_funcoes_bd("tabela inicial");
$conexao->$local = "localhost ou ip do servidor";
$conexao->$bd = "Nome do Banco";
$conexao->$usuario = "Nome do Usuario";
$conexao->$senha = "Senha do Usuario";
$conexao->$tipobd = "mysql";
$conexao->conectar();
?>

1.2) Inserindo Dados em uma Tabela do Banco

Para inserir dados no banco, o método mais fácil é o $instar->cad($valores, $ignorados) que irá receber um Array com o nome dos campos da tabela e seus respectivos valores. Simples assim, o sistema faz o código SQL de insert com segurança e de forma automática.

< ? php 
					
// Exemplo 1: Imagine que tenhamos a tabela jornal com os seguintes campos: joCodigo, joNome, joEdicao, joAtiva.

$instar->tabela = "jornal";
$dado["joNome"] = "Edição deste Jornal";
$dado["joEdicao"] = "100";
$dado["joAtiva"] = "S";

$instar->cad($dado);
?>

< ? php 
					
/* Exemplo 2: Imagine que tenhamos a tabela jornal com os seguintes campos: joCodigo, joNome, joEdicao, joAtiva. 
Supondo queremos inserir os dados enviados através de um formulário.
Nesse caso é uma mão na roda, pois basta que os Nomes dos Campos dos formulários sejam iguais aos nomes dos campos na tabela e esta feita a mágica. O sistema automaticamente identifica os que fazem parte da tabela e ignora os nomes que não existem no banco.
Caso haja algum campo que deva ser ignorado nesse registro e só passar o seu nome no Array $ignorados.
*/

$instar->tabela = "jornal"; 
$instar->cad($_POST, $ignorados);
?>

Os valores NUNCA devem ser passados diretamente no código SQL, pois tal fato enseja margem para o SQL Injection, técnica tão manjada atualmente e que ainda faz muitas vitimas. Por esse motivo os valores devem ser escapados do SQL.

Obs: Muitos códigos da Instar estão dessa maneira e por isso não estão 100% protegidos de SQL Injection.

1.3) Atualizando Dados de uma Tabela do Banco

Para atualizar os dados de um registro no banco de dados é muito parecido com a inserção, utilizamos o método $instar->atu($valores, $ignorados) seguido do Array com parâmetros e valores e do array de ignorados. A atualização precisa definir qual linha atualizar, ou seja é necessário adicionar filtros ao código.

Iremos introduzir aqui alguns outros métodos para que seja realizada a atualização de dados em uma tabela.

O mais importante deles é o método $instar->addFiltro($campo,$op, $valor = "", $cond = "")

O parâmetro $op é o nosso operador, você poderá passar os seguintes operadores: = , != , > , <, >=, <=, NULO, NAO NULO e CONTEM. Passar um operador que não existe ocasionará em erro de programação.

O parâmetro $cond é o nosso condicionador, você poderá passar os seguintes condicionares: E , OU. Passar um condicionador que não existe ocasionará em erro de programação.

Você apenas usa o parâmetro $cond se houver algum outro filtro mais para frente se você chamar só 1 filtro ou este for último passar este parâmetro ocasionára um erro de programação.

* Sem este método para definir um código especifico você atualizaria todas as linhas de sua tabela. Na realidade perderia todos os outros dados registrados para que isso não ocorrer é necessário chamar este metodo e filtrar pelo código.

* GUARDE BEM O FUNCIONAMENTO DESTE MÉTODO, ELE É MUITO IMPORTANTE, POIS ELE SERÁ UTILIZADO TANTO PARA FILTRO DE EDIÇÃO, COMO PARA CONSULTA E REMOÇÃO.

Voltemos ao exemplo da atualização:

< ? php 
					
// ATUALIZANDO UM REGISTRO	
$instar->tabela = "jornal";
$jo["joNome"] = "Outro Nome";
$instar->addFiltro("joCodigo","=","20");
$instar->atu($jo);
?>

Note que no exemplo acima estamos atualizando somente a linha do Jornal com código 20 e não as demais as linhas.

1.4) Removendo Dados de uma Tabela do Banco

< ? php 
					

// Utilizando chamada com interface fluída, o que é suporte para as funções de banco de dados
$instar->
          tudo()->
          addFiltro("joCodigo","<","28")->
          ordenar("joCodigo", "DESC")->
          ordenar("joNome", "ASC")->
          limitar("2")->rem();
?>

1.5) Consultando Dados de uma Tabela no Banco

< ? php 
					
// Consultando um banco de dados
$instar->tabela = "administracao";
$dados = $instar->addRelacionamento("departamentos","ad_departamentos_deCodigo","=","deCodigo")->sel();
	
if($dados["registros"] > 0)
{
    foreach($dados["dados"] as $dado)
	{
		echo $dado["adNome"]. "
";
	}
}
?>

1.6) Consultas mais Complexas

 

Consultas mais complexas com o mysql são raras de acontecerem podem ser realizadas utilizando os métodos

$instar->addInstrucao($instrucao, array $parametros = NULL)

< ? php 
					
// Consultando um banco de dados
$instar->tabela = "administracao";

$instar->addInstrucao(" ( ")
$instar->addRelacionamento("departamentos","ad_departamentos_deCodigo","=","deCodigo");
$instar->addInstrucao(" ) ");
$dados = $instar->sel();
	
if($dados["registros"] > 0)
{
    foreach($dados["dados"] as $dado)
	{
		echo $dado["adNome"]. "
";
	}
}
?>

2. ENVIO DE ARQUIVOS

Para o envio de arquivos existe a classe instar_funcoes_arquivos

Essa classe contem funções para enviar arquivos, deletar arquivos, procurar no arquivo e substituir uma palavra entre outras...

2.1 Instanciando uma classe arquivos e fazendo envio de um arquivo

O método mais comum a ser chamada é o

instar_enviar($arquivo, $destino, $extensoes) - onde arquivo é o $_FILE recebido do formulário, destino é a pasta no servidor onde devem ser salvo os arquivos e o último parâmetro são as extensões permitidas a enviar, elas devem ser separadas por , exemplo: doc,docx,pdf

No exemplo abaixo imaginemos que exista o campo html do tipo file com o nome de diArquivo

< ? php 
					
	require "funcoes_instar/instar_funcoes_arquivos.php";	

	if($_FILES['diArquivo']['tmp_name'] != '')
	{
		$envio = new instar_funcoes_arquivos();
		$_POST['diArquivo'] = $envio->instar_enviar($_FILES['diArquivo'],'../uploads', "pdf");
		if(isset($_POST["diArquivo"]["erro"]["msg"]) ) {
			echo "";	
		}
	}
?>

Após o envio do arquivo essa função retornara automaticamente o novo nome do arquivo pois ela faz todo um tratamento de retirada de caracteres estranhos e define também um nome único para que não haja duplicidade na pasta dos arquivos.

Caso ocorra algum erro este método retornara o arry $retorno["erro"]["msg"] explicando o que ocorreu.

Nos nossos sistemas é pratica comum que seja realizada uma validação se deu certo afim de não alterar o arquivo que já estava la caso tenha ocorrido algum erro ficando da seguinte forma:

< ? php 
					
	// ENVIO DE ARQUIVOS INSTAR
	require "funcoes_instar/instar_funcoes_arquivos.php";	

	if($_FILES['diArquivo']['tmp_name'] != '')
	{
		$envio = new instar_funcoes_arquivos();
		$_POST['diArquivo'] = $envio->instar_enviar($_FILES['diArquivo'],'../uploads', "pdf");
		if(isset($_POST["diArquivo"]["erro"]["msg"]) ) {
			echo "";	
		}
	}
	
	if( isset($_POST['diArquivo']['erro']['msg']) || ($_FILES['diArquivo']['tmp_name'] == '') )
	{	
		$instar->tabela = "diario_oficial";
		$_POST['diArquivo'] = $instar->addFiltro("diCodigo","=",(int) $_POST['id'])->limitar(1)->sel_campo("diArquivo");
	}
	// FIM ENVIO DE ARQUIVOS INSTAR
?>