Você pode criar uma instância de uma classe adaptadora usando seu construtor. Um construtor de classe adaptadora leva um argumento, que é um matriz de parâmetros usado para declarar a conexão.

$db = new Zend_Db_Adapter_Pdo_Mysql(array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));

Como uma alternativa ao uso direto do construtor da classe adaptadora, você pode criar uma instância de uma adaptadora usando o método estático Zend_Db::factory(). Este método carrega dinamicamente o arquivo da classe adaptadora sob demanda usando o método Zend_Loader::loadClass().

O primeiro argumento é um string que identifica o nome base da classe adaptadora. Por exemplo, a string 'Pdo_Mysql' corresponde à classe Zend_Db_Adapter_Pdo_Mysql. O segundo argumento é a mesma matriz de parâmetros que você teria passado para o construtor da adaptadora.

// Nós não precisamos seguir a declaração a seguir porque o
// arquivo Zend_Db_Adapter_Pdo_Mysql será carregado para nós pelo método Zend_Db
// factory.

// require_once 'Zend/Db/Adapter/Pdo/Mysql.php';

// Carrega automaticamente a classe Zend_Db_Adapter_Pdo_Mysql
// e cria uma instância dela.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));

Se você criar sua própria classe que estende Zend_Db_Adapter_Abstract, mas não nomear sua classe com o prefixo de pacote "Zend_Db_Adapter", você pode usar o método factory() para carregar sua adaptadora se você especificar a parte principal da classe adaptadora com a chave 'adapterNamespace' na matriz de parâmetros.

// Nós não precisamos carregar o arquivo da classe adaptadora
// porque ele será carregado para nós pelo método de fábrica do Zend_Db.

// Carrega automaticamente a classe MyProject_Db_Adapter_Pdo_Mysql e cria
// uma instância dela.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'             => '127.0.0.1',
    'username'         => 'webuser',
    'password'         => 'xxxxxxxx',
    'dbname'           => 'test',
    'adapterNamespace' => 'MyProject_Db_Adapter'
));

Opcionalmente, você pode especificar cada argumento do método factory() como um objeto do tipo Zend_Config.

Se o primeiro argumento é um objeto de configuração, espera-se que ele contenha uma propriedade chamada adapter, contendo uma string que designa a base do nome da classe adaptadora. Opcionalmente, o objeto pode conter uma propriedade chamada params, com subpropriedades correspondentes aos nomes de parâmetro da adaptadora. Isso é usado somente se o segundo argumento do método factory() for omitido.

$config = new Zend_Config(
    array(
        'database' => array(
            'adapter' => 'Mysqli',
            'params'  => array(
                'host'     => '127.0.0.1',
                'dbname'   => 'test',
                'username' => 'webuser',
                'password' => 'secret',
            )
        )
    )
);

$db = Zend_Db::factory($config->database);

O segundo argumento do método factory() pode ser um matriz associativo contendo entradas correspondentes aos parâmetros da adaptadora. Esse argumento é opcional. Se o primeiro argumento é do tipo Zend_Config, é assumido que ele contém todos os parâmetros, e o segundo argumento é ignorado

A seguinte lista explica parâmetros comuns reconhecidos pelas classes adaptadoras Zend_Db.

$options = array(
    Zend_Db::CASE_FOLDING => Zend_Db::CASE_UPPER
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Db2', $params);

$options = array(
    Zend_Db::AUTO_QUOTE_IDENTIFIERS => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

$pdoParams = array(
    PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'driver_options' => $pdoParams
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

echo $db->getConnection()
        ->getAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY);

$options = array(
    Zend_Db::ALLOW_SERIALIZATION => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

Criar uma instância de uma classe adaptadora não abre uma conexão com o servidor SGBDR imediatamente. A adaptadora guarda os parâmetros de conexão, e a estabelece por demanda, na primeira vez que você precisar executar uma consulta. Isso garante que criar um objeto adaptador é rápido é barato. Você pode criar uma instância de uma adaptadora mesmo se não estiver certo que precisa rodar quaisquer consultas de banco de dados durante a requisição atual que sua aplicação está servindo.

Se você precisa forçar a adaptador a se conectar ao SGBDR, use o método getConnection(). Esse método retorna um objeto para a conexão como representado pela respectiva extensão de banco de dados PHP. Por exemplo, se você usar qualquer uma das classes adaptadoras para drivers PDO, então getConnection() retorna o objeto PDO, depois de iniciá-lo como uma conexão ativa para o banco de dados especificado.

Pode ser útil forçar a conexão se você quer capturar quaisquer exceções que ela lançar como resultado de credenciais de conta inválidas, ou outra falha ao conectar-se ao servidor SGBDR. Essas exceções não são lançadas até que a conexão seja feita, assim isso pode ajudar a simplificar o código de sua aplicação se você manipular as exceções em um lugar, em vez de fazê-lo na primeira consulta ao banco de dados.

Adicionalmente, uma adaptadora pode ser serializada para armazená-la, por exemplo, em uma variável de sessão. Isso pode ser muito útil não somente para a própria adaptadora, mas para outros objetos que a agreguem, como um objeto Zend_Db_Select. Por padrão, adaptadoras têm permissão de serem serializadas, se você não quiser isso, deve considerar passar a opção Zend_Db::ALLOW_SERIALIZATION com FALSE, veja o exemplo abaixo. Em respeito ao princípio de conexões preguiçosas, a adaptadora não reconectará a si própria depois de ser revertida sua serialização. Você deve então chamar getConnection() por conta própria. Você pode fazer a adaptadora se autorreconectar pela passagem de Zend_Db::AUTO_RECONNECT_ON_UNSERIALIZE com TRUE como uma opção da adaptadora.

try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // talvez uma credencial de login falhou, ou talvez o SGBDR não está rodando
} catch (Zend_Exception $e) {
    // talvez factory() falhou em carregar a classe adaptadora especificada
}

Você pode rodar uma consulta SQL SELECT e recuperar seus resultados em um passo usando o método fetchAll().

O primeiro argumento para este método é uma string contendo uma declaração SELECT. Como alternativa, o primeiro argumento pode ser um objeto da classe Zend_Db_Select. A classe adaptadora converte automaticamente esse objeto em uma representação de string da declaração SELECT.

O segundo argumento para fetchAll() é um matriz de valores para substituir por curingas de parâmetro na declaração SQL.

$sql = 'SELECT * FROM bugs WHERE bug_id = ?';

$result = $db->fetchAll($sql, 2);

Por padrão, fetchAll() retorna um matriz de linhas, cada uma das quais é um matriz associativo. As chaves do matriz associativo são as colunas ou apelidos de coluna dados na consulta de seleção.

Você pode especificar um estilo diferente de resultados de busca usando o método setFetchMode(). Os modos suportados são identificados por constantes:

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAll('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result é um matriz de objetos
echo $result[0]->bug_description;

O método fetchAssoc() retorna dados em uma matriz de matrizes associativas, independente de qual valor você tenha configurado para o modo de busca, utilizando a primeira coluna como índice da matriz.

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAssoc(
    'SELECT bug_id, bug_description, bug_status FROM bugs'
);

// $result é uma matriz de matrizes associativas, conforme o modo de busca
echo $result[2]['bug_description']; // Descrição do Bug #2
echo $result[1]['bug_description']; // Descrição do Bug #1

O método fetchCol() retorna dados em um matriz de valores, independente do valor que você tenha configurado para o modo de busca Ele devolve somente a primeira coluna devolvida pela consulta. Quaisquer outras colunas devolvidas pela consulta são descartadas. Se você precisar devolver uma outra coluna que não seja a primeira, veja esta seção.

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchCol(
    'SELECT bug_description, bug_id FROM bugs WHERE bug_id = ?', 2);

// contém bug_description; bug_id não é devolvida
echo $result[0];

O método fetchPairs() retorna dados em um matriz de pares chave-valor, como um matriz associativo com uma entrada única por linha. A chave desse matriz associativo é tomada da primeira coluna devolvida pela consulta SELECT. O valor é tomado da segunda coluna devolvida pela consulta SELECT. Quaisquer outras colunas devolvidas pela consulta são descartadas.

Você deve projetar a conuslta SELECT de modo que a primeira coluna devolvida tenha valores únicos. Se há valores duplicados na primeira coluna, entradas na matriz associativo serão sobrescritas.

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchPairs('SELECT bug_id, bug_status FROM bugs');

echo $result[2];

O método fetchRow() retorna dados usando o modo de busca atual, mas retorna somente a primeira linha buscada a partir do conjunto de resultados.

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchRow('SELECT * FROM bugs WHERE bug_id = 2');

// note que $result é um único objeto, não um matriz de objetos
echo $result->bug_description;

O método fetchOne() é como uma combinação do método fetchRow() com o método fetchCol(), no que ele retorna dados somente para a primeira linha buscada a partir do conjunto de resultados, e retorna somente o valor da primeira coluna naquela linha. Portanto ele retorna somente um único valor escalar, nem um matriz nem um objeto.

$result = $db->fetchOne('SELECT bug_status FROM bugs WHERE bug_id = 2');

// este é um valor string único
echo $result;

Você pode adicionar novas linhas em uma tabela de seu banco de dados usando o método insert(). O primeiro argumento é uma string que denomina a tabela, e o segundo argumento é um matriz associativo, mapeando nomes de coluna para valores de dados.

$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);

Colunas que você excluir da matriz de dados não serão especificadas para o banco de dados. Portanto, elas seguem as mesmas regras que uma declaração SQL INSERT segue: se a coluna tem uma cláusula DEFAULT, a coluna leva o valor na linha criada, caso contrário é deixado em um estado NULL.

Por padrão, os valores em seu matriz de dados são incluídos usando parâmetros. ISso reduz o risco de alguns tipos de problemas de segurança. Você não precisa aplicar escaping ou quoting para valores na matriz de dados.

Você pode precisar que valores na matriz de dados sejam tratados como expressões SQL, caso no qual elas não devam sofrer quoting. Por padrão, todos os valores de dados passados como strings são tratados como literais string. Para especificar que o valor é uma expressão SQL e portanto não deve sofrer quoting, passe o valor na matriz de dados como um objeto do tipo Zend_Db_Expr em vez de texto claro.

$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);

Algumas marcas de SGBDR suportam autoincremento de chaves primárias. Uma tabela definida desse modo gera um valor de chave primária automaticamente durante um INSERT de uma nova linha. O valor de retorno do método insert() não é o último ID incluído, porque a tabela pode não ter uma coluna de autoincremento. Em vez disso, o valor de retorno é o número de linhas afetadas (geralmente 1).

Se sua tabela é definida com uma chave primária de autoincremento você pode chamar o método lastInsertId() depois da inclusão. Esse método retonra o último valor gerado no escopo da conexão atual com o banco de dados.

$db->insert('bugs', $data);

// retorna o último valor gerado por uma coluna de autoincremento
$id = $db->lastInsertId();

Algumas marcas de SGBDR suportam um objeto de sequencia, que gera valores únicos para servir como valores da chave primária. Para suportar sequencias, o método lastInsertId() aceita dois argumentos string opcionais. Esses argumentos denominam a tabela e a coluna, assumindo que você tenha seguido a convenção de que uma sequencias é denominada usando os nomes de tabela e coluna para os quais a sequencia gera valores, e um sufixo "_seq". Isso é baseado na convenção usada pelo PostgreSQL quando nomeia sequencias para colunas SERIAL. Por exemplo, uma tabela "bugs" com a coluna de chave primária "bug_id" usaria uma sequencia denominada "bugs_bug_id_seq".

$db->insert('bugs', $data);

// retorna o último valor gerado pela sequencia 'bugs_bug_id_seq'.
$id = $db->lastInsertId('bugs', 'bug_id');

// alternativamente, retorna o último valor gerado pela sequencia 'bugs_seq'.
$id = $db->lastInsertId('bugs');

Se o nome de seu objeto de sequencia não seguir essa convenção de nomes, use o método lastSequenceId() em seu lugar. Esse método leva um único argumento string, nomeando literalmente a sequencia.

$db->insert('bugs', $data);

// retorna o último valor gerado pela sequencia 'bugs_id_gen'.
$id = $db->lastSequenceId('bugs_id_gen');

Para as marcas de SGBDR que não suportam sequencias, incluindo MariaDB, MySQL, Microsoft SQL Server, e SQLite, os argumentos para o método lastInsertId() são ignorados, e o valor devolvido é o valor mais recente gerado para qualquer tabela por operações INSERT durante a conexão atual. Para essas marcas de SGBDR, o método lastSequenceId() sempre devolve NULL.

Você pode atualizar linhas em uma tabela de banco de dados usando o método update() de uma adaptadora. Esse método leva três argumentos: o primeiro é o nome da tabela, o segundo é um matriz associativo mapeando as colunas a serem alteradas para os novos valores a serem atribuídos a essas colunas.

Os valores na matriz de dados são tratados como sequências de caracteres. Veja esta seção para obter informações sobre como utilizar expressões SQL na matriz de dados.

O terceiro argumento é uma string contendo uma expressão SQL que é usada como critério para as linhas a serem alteradas. Os valores e identificadores nesse argumento não são citados ou escapados. Você é responsável por garantir que o conteúdo dinâmico seja interpolados para essa sequência de forma segura. Veja esta seção para métodos que o ajudam a fazer isso.

O valor de retorno é o número de linhas afetadas pela operação de atualização.

$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$n = $db->update('bugs', $data, 'bug_id = 2');

Se você omitir o terceiro argumento, então todas as linhas na tabela do banco de dados são atualizadas com os valores especificados no matriz de dados.

Se você fornecer um matriz de strings como terceiro argumento, essas strings são unidas como termos em uma expressão separada por operadores AND.

Se você fornecer um matriz de matrizs como terceiro argumento, os valores serão automaticamente citados dentro das chaves. Esses serão então unidos como termos, separados por operadores AND.

$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where[] = "reported_by = 'goofy'";
$where[] = "bug_status = 'OPEN'";

$n = $db->update('bugs', $data, $where);

// A SQL resultante é:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')

$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where['reported_by = ?'] = 'goofy';
$where['bug_status = ?']  = 'OPEN';

$n = $db->update('bugs', $data, $where);

// A SQL resultante é:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')

Você pode excluir linhas de uma tabela de banco de dados usando o método delete()methodName>. Esse método leva dois argumentos: O primeiro é uma string com o nome da tabela.

O segundo argumento é uma string contendo uma expressão SQL que é usada como critério para as linhas a eliminar. Os valores e identificadores nesse argumento não são citados ou escapado. Você é responsável por garantir que o conteúdo dinâmico seja interpolado para esta seqüência de forma segura. Veja esta seção para métodos que o ajudam a fazer isso.

O valor de retorno é o número de linhas afetadas pela operação de exclusão.

$n = $db->delete('bugs', 'bug_id = 3');

Se você omitir o segundo argumento, o resultado é que todas as linhas na tabela do banco de dados são eliminadas.

Se você fornecer um matriz de strings como o segundo argumento, essas strings são unidas como termos em uma expressão separada por operadores AND.

Se você fornecer um matriz de matrizs como segundo argumento, os valores serão automaticamente citados dentro das chaves. Esses serão então unidos como termos, separados por operadores AND.

O método quote() aceita um único argumento, um valor string escalar. Ele retorna o valor com caracteres especiais de uma forma adequada para o SGBDR que você está usando, e rodeado por delimitadores de valor de string. O delimitador de valor de string padrão SQL é o apóstrofo ( ').

$name = $db->quote("O'Reilly");
echo $name;
// 'O\'Reilly'

$sql = "SELECT * FROM bugs WHERE reported_by = $name";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'

Note que o valor de retorno de quote() inclui os delimitadores de citação em torno da cadeia. Isso é diferente de algumas funções que escapam caracteres especiais, mas não adicionam os delimitadores de citação, por exemplo mysql_real_escape_string() .

Os valores podem precisar ser citados ou não citados de acordo com o contexto de tipo de dados SQL em que eles são usados. Por exemplo, em algumas marcas de SGBDR, um valor inteiro não deve ser citado como uma string se for comparado a uma coluna ou expressão do tipo inteiro. Em outras palavras, o código seguinte é um erro em algumas implementações SQL, assumindo que intColumn tem um tipo de dados SQL INTEGER

SELECT * FROM atable WHERE intColumn = '123'

Você pode usar o segundo argumento opcional para o método quote() para aplicar citação seletivamente para o tipo de dados SQL que você especificar.

$value = '1234';
$sql = 'SELECT * FROM atable WHERE intColumn = '
     . $db->quote($value, 'INTEGER');

Cada classe Zend_Db_Adapter tem codificada os nomes de tipos de dados SQL numéricos para a respectiva marca de SGBDR. Você também pode usar as constantes Zend_Db::INT_TYPE, Zend_Db::BIGINT_TYPE, e Zend_Db::FLOAT_TYPE para escrever código de uma forma mais independente de SGBDR.

Zend_Db_Table especifica SQL para quote() automaticamente ao gerar consultas SQL que referenciam colunas-chave de uma tabela.

O uso mais típico de citação é para interpolar uma variável PHP em uma expressão ou declaração SQL. Você pode usar o método quoteInto() para fazer isso em uma única etapa. Esse método leva dois argumentos: o primeiro argumento é uma string contendo um símbolo marcador (?), e o segundo argumento é um valor ou variável PHP que deve ser substituída pelo marcador.

O símbolo marcador é o mesmo símbolo usado por muitas marcas de SGBDR para parâmetros posicionais, mas o método quoteInto() apenas emula parâmetros de consulta. O método simplesmente interpola o valor para a string, escapa caracteres especiais, e aplica apóstrofos em torno dele. Parâmetros de consulta verdadeiros mantêm a separação entre a string SQL e os parâmetros assim que a declaração é analisada no servidor SGBDR.

$sql = $db->quoteInto("SELECT * FROM bugs WHERE reported_by = ?", "O'Reilly");

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'

Você pode usar o terceiro parâmetro opcional de quoteInto() para especificar o tipo de dados SQL. Tipos de dados numéricos não são citados, e outros tipos são citados.

$sql = $db
    ->quoteInto("SELECT * FROM bugs WHERE bug_id = ?", '1234', 'INTEGER');

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 1234

Os valores não são a única parte da sintaxe SQL que pode precisar ser variável. Se você usar variáveis PHP para nomear tabelas, colunas, ou outros identificadores em suas declarações SQL, pode ser necessário citar essas strings também. Por padrão, identificadores SQL têm regras de sintaxe como PHP e a maioria das outras linguagens de programação. Por exemplo, os identificadores não devem conter espaços, certas pontuações ou caracteres especiais, ou ainda caracteres internacionais. Certas palavras também são reservadas para a sintaxe SQL, e não devem ser usadas como identificadores.

No entanto, SQL tem um recurso chamado identificadores delimitados, que permite escolhas mais amplas para a grafia de identificadores. Se você colocar um identificador SQL no tipo adequado de aspas, pode usar identificadores com dados que seriam inválidos sem as aspas. Identificadores delimitados podem conter espaços, pontuação, ou caracteres internacionais. Você também pode usar palavras reservadas da SQL se colocá-las em identificadores delimitados.

O método quoteIdentifier() trabalha como quote(), mas ele aplica caracteres delimitadores de identificador para a string de acordo com o tipo de adaptador que você usar. Por exemplo, a SQL padrão usa aspas duplas (") para delimitadores de identificador, e a maioria das marcas de SGBDR marcas usam esse símbolo. O MySQL usa crase (`) por padrão. O método quoteIdentifier() também escapa caracteres especiais dentro do argumento string.

// podemos deter um nome de tabela que é uma palavra reservada SQL
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"

Identificadores delimitados SQL são sensíveis à caixa, ao contrário de identificadores não citados. Portanto, se você usar identificadores delimitados, você deve usar a ortografia do identificador exatamente como ela é armazenada no seu esquema, incluindo a caixa das letras.

Na maioria dos casos onde SQL é gerada dentro de classes Zend_Db, o padrão é que todos os identificadores sejam delimitados automaticamente. Você pode alterar esse comportamento com a opção Zend_Db::AUTO_QUOTE_IDENTIFIERS . Especifique essa opção ao instanciar o adaptador. Veja este exemplo.