Icecream
Modules > Classes > Icecream
O Icecream é um ORM (Object-relational mapping) responsável por realizar consultas de Banco de Dados de maneira estruturada.
Estrutura Básica
Assim que o banco de dados foi configurado, basta instanciar o módulo Icecream para realizar uma requisição ao banco de dados.
use Icecream\ Icecream;\n
$db = new Icecream($table, $alias);
$table: string "nome_da_tabela" Recebe o nome da tabela\n
$alias: string "tb" (Opcional) Recebe o alias da tabela\n
No exemplo acima, basta utilizar a variável $db para executar funções relacionadas a essa tabela para receber os resultados, podendo linkar várias opções num mesmo banco.
Exemplo 1
use Icecream\ Icecream;\n
$db = new Icecream($table, $alias);\n
$db->where("idade", "50" );\n
$db->orderBy("nome", "ASC");\n
$resultado = $db->select();
Exemplo 2
use Icecream\ Icecream;\n
$db = new Icecream($table, $alias)\n
$resultado = $db\n
->where("idade", "50" )\n
->orderBy("nome", "ASC")\n
->select();
Models
Ao utilizar Models você cria um caminho mais fácil para acesso às tabelas. Para criar um novo Model, basta criar um arquivo dentro da pasta Models com o mesmo nome de sua classe. O model deverá extender a classe IcecreamModel.
Criando um Model
Abaixo você pode verificar a maneira mais rápida e simples de criar um Model.
use Icecream\ IcecreamModel;\n\n
class TabelaModel extends IcecreamModel
{
const TABLE = "nome_da_tabela";
}
Caso precise executar funções adicionais, basta utilizar a função function __construct.
use Icecream\ IcecreamModel;\n\n
class TabelaModel extends IcecreamModel
{
const TABLE = "nome_da_tabela";\n\n
public function __construct()
{
parent::__construct();\n
$this->setServer('nome_outro_servidor');
}
}
Sempre que utilizar o método construir em seu Model, você deve chamar a função parent::__construct() para que as funções padrão do módulo sejam executadas.
Utilizando o Model
Você poderá instanciar seu Model para ter uma estrutura de dados...
$tabela = new TabelaModel();\n
$resultados = $tabela->select();\n
return $resultados;
...ou pode também utilizar uma instância rápida
$resultados = TabelaModel()::open()->select();\n
return $resultados;
Gerar Models automaticamente
Se já tiver criado seu banco de dados, você pode utilizar o método automático do Icecream para gerar suas Models. Basta abrir o console na pasta do seu projeto e inserir o comando php console Icecream/Icecream:generateModels. Lembre-se de que essa função irá deletar quaisquer Models criados.
Condição
Existem diversos tipos de condições que podem ser aplicadas. Elas são equivalente à clausula WHERE do SQL.
Funções
where($column, $operator, $value);
$column Recebe o nome do campo
$operator Operador de comparação (=, >, <, !=, etc)
$value Recebe o nome do campo
Query SQL correspondente
WHERE column = '$value' AND ...
Caso o operador seja "=", pode-se passar apenas os dois parâmetros como $column e $value.
orWhere($column, $operator, $value);
$column Recebe o nome do campo
$operator Operador de comparação (=, >, <, !=, etc)
$value Recebe o nome do campo
WHERE column = '$value' OR ...
whereNot($column, $value);
$column Recebe o nome do campo
$value Recebe o nome do campo
WHERE column != '$value' AND ...
orWhereNot($column, $value);
$column Recebe o nome do campo
$value Recebe o nome do campo
WHERE column != '$value' OR ...
whereBetween($column, $valueFrom, $valueTo);
$column Recebe o nome do campo
$valueFrom Valor inicial
$valueTo Valor final
WHERE column BETWEEN ('$valueFrom','$valueTo') AND ...
orWhereBetween($column, $valueFrom, $valueTo);
$column Recebe o nome do campo
$valueFrom Valor inicial
$valueTo Valor final
WHERE column BETWEEN ('$valueFrom','$valueTo') OR ...
whereNull($column);
$column Recebe o nome do campo
WHERE column IS NULL AND ...
orWhereNull($column);
$column Recebe o nome do campo
WHERE column IS NULL OR ...
whereNotNull($column);
$column Recebe o nome do campo
WHERE column IS NOT NULL AND ...
orWhereNotNull($column);
$column Recebe o nome do campo
WHERE column IS NOT NULL OR ...
whereLike($column, $statement);
$column Recebe o nome do campo
$statement Recebe o nome do campo
WHERE column LIKE '$statement' AND ...
orWhereLike($column, $statement);
$column Recebe o nome do campo
$statement Recebe o nome do campo
WHERE column LIKE '$statement' OR ...
whereNotLike($column, $statement);
$column Recebe o nome do campo
$statement Recebe o nome do campo
WHERE column NOT LIKE '$statement' AND ...
orWhereNotLike($column, $statement);
$column Recebe o nome do campo
$statement Recebe o nome do campo
WHERE column NOT LIKE '$statement' OR ...
whereIn($column, $list);
$column Recebe o nome do campo
$lista Recebe os valores em array ou uma instância de outra tabela do Icecream
WHERE column IN (0,1,2,3) AND ...
Ao enviar uma instância de outra tabela do Icecream:
WHERE column IN (SELECT column FROM table) AND ...
orWhereIn($column, $list);
$column Recebe o nome do campo
$lista Recebe os valores em array ou uma instância de outra tabela do Icecream
WHERE column IN (0,1,2,3) OR ...
Ao enviar uma instância de outra tabela do Icecream:
WHERE column IN (SELECT column FROM table) OR ...
whereNotIn($column, $list);
$column Recebe o nome do campo
$lista Recebe os valores em array ou uma instância de outra tabela do Icecream
WHERE column NOT IN (0,1,2,3) AND ...
Ao enviar uma instância de outra tabela do Icecream:
WHERE column NOT IN (SELECT column FROM table) AND ...
orWhereNotIn($column, $list);
$column Recebe o nome do campo
$lista Recebe os valores em array ou uma instância de outra tabela do Icecream
WHERE column NOT IN (0,1,2,3) OR ...
Ao enviar uma instância de outra tabela do Icecream:
WHERE column NOT IN (SELECT column FROM table) OR ...
Sub-Condição
É possível criar uma sub-condição, permitindo vários filtragens mais detalhadas de dados. Para isso, basta instanciar a classe new Icecream\Condition() e incluir as seleções de Where, como mostrado acima.
Para aplicar a sub-condição numa consulta, utilize a função $db->condition($condition);
Essa código...
$db = new Icecream("produtos");\n
$db->where("ativo", 1);\n\n
$condition = new Condition();\n
$condition->where("categoria", 2);\n
$condition->orWhere("categoria", 3);\n\n
$db->condition($condition);
...gerará a seguinte consulta
SELECT * FROM produtos WHERE ativo = 1 AND (categoria = 2 OR categoria = 3)
Filtros
columns($columns);
$columns Recebe o nome das colunas a serem consultadas. Pode ser um array ou uma string
orderBy($column, $sort);
$column Recebe o nome da coluna
$sort (opcional) Recebe a ordem de organização
... ORDER BY $column $sort
Caso não informe $sort, o padrão será ASC
limit($limit);
$limit Inteiro com o limite de dados
offset($offset);
$offset Inteiro com o deslocamento de dados
... LIMIT $limit OFFSET $offset
Para utilizar o Offset, é necessário incluir também o Limit, de acordo com as necessidades do SQL.
groupBy($columns);
$columns Recebe o nome das colunas a serem agrupadas. Pode ser um array ou uma string
distinct();
Inclui a cláusula DISTINCT no início da query
União
As funções de união também são práticas para a criar a cláusula JOIN nas tabelas.
Todas as funções de join possuem a mesma estrutura, como demonstrado abaixo:
join($table, $column, $operator, $column2);
$table Recebe o nome da tabela ou uma instância de tabela Icecream.
$column Recebe o nome da coluna da tabela a ser unida.
$operator (Opcional) Recebe o operador de comparação entre as duas colunas.
$column2 Recebe o nome da coluna da tabela atual correspondente.
JOIN $table ON $table.$column = tabela.$column2
Caso o operador seja "=", pode-se passar apenas os dois parâmetros como $column e $column2 (no lugar de $operator).
Utilizando oeprador padrão (=)
$join("tabela2", "colDaTabela2", "colDaTabela1");
JOIN tabela2 ON tabela2.colDaTabela2 = tabela.colDaTabela1
Utilizando operador diferente
$join("tabela2", "colDaTabela2", "!=", "colDaTabela1");
JOIN tabela2 ON tabela2.colDaTabela2 != tabela.colDaTabela1
Perceba que o código SQL gerado automaticamente inclui o nome da tabela juntamente do nome da coluna. Você ainda poderá atribuir um alias que preferir.
Unindo tabelas em sub-queries
Caso você passe uma instância de um outro banco para a tabela do join, o mesmo será adicionado como uma subquery.
Essa instrução...
$tabela1 = new Icecream("tabela1");\n
$tabela2 = new Icecream("tabela2");\n
$tabela1->join($tabela2, 'id', 'id');\n
... gera essa query
SELECT * FROM tabela1 JOIN (SELECT * FROM tabela2) AS tabela2 ON tabela2.id = tabela1.id
Outros tipos de Join
leftJoin($table, $column, $operator, $column2);
LEFT JOIN $table ON $table.$column = tabela.$column2
rightJoin($table, $column, $operator, $column2);
RIGHT JOIN $table ON $table.$column = tabela.$column2
outerJoin($table, $column, $operator, $column2);
OUTER JOIN $table ON $table.$column = tabela.$column2
innerJoin($table, $column, $operator, $column2);
INNER JOIN $table ON $table.$column = tabela.$column2
Busca
A função search() tem por objetivo realizar uma busca mais profunda de dados dentro de uma coluna. A partir dela, os resultados podem ser buscados inteiramente, separadamente e em várias partes dos valores.
search($columns, $term, $types);
$columns Recebe o nome das colunas nas quais o termo deve ser buscado
$term Termo a ser buscado
$types (Opcional) Tipos de busca a ser realizada
Tipos de busca
É possível passar um ou mais tipos (através de array) para realizar a busca.
Icecream::SEARCH_EQUAL Campo com o valor identico ao termo pesquisado.
Icecream::SEARCH_START Busca pelo termo no início do valor do campo.
Icecream::SEARCH_END Busca pelo termo no fim do valor do campo.
Icecream::SEARCH_ANY Busca pelo termo em qualquer parte do valor do campo.
Inserção
insert($values, $map);
$values Array sequencial ou associativo de valores
$map (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa
A variável $values poderá receber um array associativo ou array sequencial, do seguinte modo:
Array Associativo
{ nome:"Eduardo", idade : 21}
INSERT INTO tabela (nome, idade), VALUES ('Eduardo', 21)
Array Sequencial
[{ nome:"Eduardo", idade : 21}, { nome:"Lucas", idade : 25}]
INSERT INTO tabela (nome, idade), VALUES ('Eduardo', 21), ('Lucas', 25)
Você também pode passar uma instância do Icecream no parâmetro $values. O código irá resgatar os valores da tabela que você passou e irá inseri-los dentro da tabela selecionada.
Alteração
update($values, $map);
$values Array associativo de valores
$sort (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa
UPDATE tabela... WHERE
A execução de um update requer a inclusão de pelo menos uma condição do tipo where.
Inserção condicional
A função place() tem por objetivo alterar um registro caso o mesmo já exista, ou inserí-lo caso não exista
place($values, $map);
$values Array de valores
$sort (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa
Se o registro não existir, insere
INSERT INTO tabela...
Se o registro existir, atualiza
UPDATE tabela... WHERE
A execução dessa função requer a inclusão de pelo menos uma condição do tipo where.
Exclusão
delete();
Remove valores de acordo com o WHERE declarado.
DELETE FROM ...
Para utilizar essa função é obrigatório utilizar ao menos uma condição.
truncate();
Zera todos os dados da tabela
TRUNCATE ...
Use essa função com cautela.
Seleção
select();
Retorna um array sequencial com todos os dados.
[
{nome:"José"},
{nome:"Vinícius"},
{nome:"Cláudia"}
]
selectFirst();
Retorna num array associativo apenas o primeiro registro
selectLast();
Retorna num array associativo apenas o último registro
selectMax($column);
$column Recebe o nome da coluna
Busca o valor máximo de uma coluna.
SELECT MAX($column) FROM ...
selectMin($column);
$column Recebe o nome da coluna
Busca o valor mínimo de uma coluna.
SELECT MIN($column) FROM ...
selectCount($column);
$column Recebe o nome da coluna
Busca a contagem a partir de uma coluna.
SELECT COUNT($column) FROM ...
selectSum($column);
$column Recebe o nome da coluna
Busca a soma dos valores de uma coluna.
SELECT SUM($column) FROM ...
Lista de Resultados
Esta função permite reorganizar os resultados de uma consulta para torná-los mais convenientes.
resultList($column, $value, $merge);
$column Recebe o nome da coluna a se tornar o índice
$valor Recebe o nome da coluna a se tornar o valor
$merge (Opcional) Caso haja valores com a mesma chave (coluna), fundí-los
Dado o seguinte resultado, verifique abaixo exemplos de uso
[
{nome:"José", id:1, idade:36},
{nome:"Vinícius", id:2, idade:23},
{nome:"Cláudia", id:3, idade:25}
]
Filtrando por chave
resultList("id");
Retorno...
[
1: {nome:"José", id:1, idade:36},
2: {nome:"Vinícius", id:2, idade:23},
3: {nome:"Cláudia", id:3, idade:25}
]
Filtrando por chave e valor
resultList("id", "nome");
Retorno...
[
1: "José",
2: "Vinícius",
3: "Cláudia"
]
Filtrando por valor
resultList(null, "nome");
Retorno...
[
"José",
"Vinícius",
"Cláudia"
]
Contagem
count();
Realiza a contagem de dados, desprezando os resultados já existentes (caso já tenha executado um select)
size();
Realiza a contagem de dados, considerando os resultados já existentes (se houver sido executado um select)
exist();
Retorna true caso a consulta retorne resultados ou false caso não retorne resultados.
Paginação
O Icecream possui uma estrutura ponta de paginação de resultados através da função paginate(). A partir dela é possível resgatar dados de paginação e também filtrar os resultados por página de maneira automatizada.
paginate($page, $perPage, $select = true, $onlyPaginate = false);
$page Número da página atual
$perPage Resultados por página
$select (Opcional) Retorna os dados já selecionados
$onlyPaginate (Opcional) Retorna apenas os dados de paginação, sem filtrar os dados
Dados paginados
O resultado retornado por uma paginação e um array com todos os dados da paginação
{
results : null,
size : 150,
totalResults : 10,
currentPage : 1,
totalPages : 15,
itemsPerPage : 10,
resultsFrom : "1",
resultsTo : "10"
}
Variáveis retornadas
results Resultados (caso $select seja true).
size Total de itens em toda a consulta (sem paginar)
totalResults Total de itens nesta consulta (paginado)
currentPage Número da página atual
totalPages Quantidade de páginas
itemsPerPage Itens por página
resultsFrom Início dos resultados
resultsTo Final dos resultados
Caso você mantenha como false o parâmetro $onlyPaginate, você poderá paginar os resultados e, em seguida, utilizar outras funções como select() ou resultList() para resgatar os valores, desprezando os resultados recebidos na variável results.
Se preferir paginar primeiro e depois obter os resultados, você pode enviar false para o parâmetro $select, evitando que os resultados sejam consultados logo na paginação.
Tabelas
existTable();
Verifica se a tabela existe
create($columns);
Cria a tabela
$columns Recebe um array associativo. Os índices são os nomes das colunas e contêm como valor um array indicando a formação das colunas.
type: string "varchar" Tipo da coluna.\n
length: string "255" (Opcional para alguns campos) Tamanho da coluna.\n
default: string "NULL" (Opcional) Valor padrão do campo.\n
key: string "unique" (Opcional) Indica se há algum tipo de chave nessa coluna ('unique' ou 'primary')
\n
\n